fimo 0.21.0-staging.2 → 0.21.0-staging.4

package/assets/agent-templates/_default/GOAL.md

@@ -9,3 +9,13 @@ Some good things to include:
 - Inputs the agent should expect (CLI args, files, API responses)
 - Anything the agent should **not** do
 - The format of the report / output the agent should produce
+
+## Decision policy
+
+Adapt these defaults to the risk and scope of this agent:
+
+- Proceed without asking when the work is within scope and a safe, reversible choice exists.
+- Ask when a missing human decision changes what the correct result should be.
+- Retain when the work is complete but all changes should be reviewed before merge.
+- Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
+- Discard when the run produced no useful changes or deliberately abandoned them.

package/assets/agent-templates/_default/capabilities.yaml

@@ -0,0 +1,10 @@
+- cms:*
+- assets:*
+- i18n:*
+- forms:*
+- webhooks:read
+- schedules:read
+- fimo:analytics:read
+- fimo:history:read
+- fimo:logs:read
+- fimo:preview:read

package/assets/content-templates/shared/types.eta

@@ -9,7 +9,7 @@
  */
 %>
 // AUTO-GENERATED ⚠️ – do not edit by hand
-import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "<%= runtimeImport %>";
+import { <%= model.runtimeTypeImports.map((typeImport) => `type ${typeImport}`).join(', ') %> } from "<%= runtimeImport %>";
 <%
 if (model.referenceImports && model.referenceImports.length > 0) {
   model.referenceImports.forEach((referenceImport) => {

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

@@ -128,7 +128,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `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`.
 - **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`.
-- **After the first successful `fimo deploy --publish`** (not the automatic first preview) → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL after first publish.
+- **After the automatic first-preview deploy on the create-new path, before the project has been published** → if there is no custom domain and the free default `*.fimo.site` slug still looks generated or was never explicitly chosen, offer to find a cleaner free subdomain. It needs no DNS. Never claim one without explicit user confirmation: suggest candidates, let the user choose, then rename it. Choosing the slug does not publish the site; the URL starts resolving only after the first successful `fimo deploy --publish`. Skip this nudge if the user already chose the default slug, attached a custom domain, or declined. See `references/domains.md` § Offer a cleaner default URL before first publish.
 - **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).
 
 ## Anti-Patterns

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

@@ -62,9 +62,11 @@ Fimo creates one task Branch and environment for a cloud run, tells the agent th
 The agent works only in that checkout. Extra branches, worktrees, and `git push` are unsupported and cannot be cleaned up
 or handed off correctly.
 
-- **Merge** when the work is ready for the target Branch. Fimo applies it or keeps any conflict for review.
-- **Retain** when a person should review the work, the run stops or fails, the agent needs an answer, or recovery may be
-  necessary. Fimo keeps the task Branch for a follow-up run.
+- **Merge** when the work is ready for the target Branch. Fimo applies the complete task environment or, if it conflicts,
+  leaves the target unchanged and keeps the work for review without choosing a side.
+- **Retain** when the completed work should be reviewed before merge, or when the run stops, fails, or may need recovery.
+  Fimo leaves the target unchanged, keeps the complete task Branch, and sends an Inbox notification asking a person to
+  review all of its changes. A later follow-up can continue from that retained work.
 - **Discard** when none of the run's work should be applied, including when it made no useful changes or deliberately
   abandoned an approach. This permanently deletes the task Branch and every change in it without review.
 
@@ -74,6 +76,49 @@ that Branch for inspection or screenshots; it does not finish or hand off the ru
 The run report is a concise outcome summary: what changed, what was verified, and what is still blocked. It is not a
 chronological account, and it should not use decorative emoji.
 
+## Define the agent's decision policy
+
+When authoring or editing an agent, add a short **Decision policy** to its `GOAL.md`. Describe the domain conditions for
+acting, asking, review, and merge; do not copy Fimo's tool protocol. Use this shape and replace the examples with rules
+specific to the agent:
+
+```md
+## Decision policy
+
+- Proceed without asking when the work is within scope and a safe, reversible choice exists.
+- Ask when a missing human decision changes what the correct result should be.
+- Retain when the work is complete but all changes should be reviewed before merge.
+- Request merge only when the result is complete, verified, and clearly safe for this agent's scope.
+- Discard when the run produced no useful changes or deliberately abandoned them.
+```
+
+Asking and review are different: `ask_user` is for a decision required before correct work can continue; `retain` ends
+the run with its complete proposal waiting for review and does not ask a question.
+
+Make those rules concrete enough that the agent can decide without guessing. For example:
+
+- **Broken-link sweeper:** fix and request merge for up to ten internal links when each replacement is unambiguous and
+  the link check passes. Ask when two plausible destinations change the page's meaning. Retain useful fixes if complete
+  verification is blocked. Discard when the scan is clean or exploratory edits were reverted.
+- **Launch-copy agent:** draft from an approved brief without asking about routine wording. Ask before choosing pricing,
+  product promises, brand direction, or deletions. Retain every completed draft for human review; never request merge.
+- **Read-only auditor:** inspect and report autonomously. Ask only when the requested scope cannot be inferred. Discard
+  the unchanged task environment after recording the report.
+- **Missing capability:** ask once for the exact capability and explain which operation it unlocks. Do not retain partial
+  work as a substitute for the blocking permission decision.
+
+A review-first content agent could use this complete policy:
+
+```md
+## Decision policy
+
+- Draft all requested copy without asking when the brief and approved source material answer the content decisions.
+- Ask before inventing a price, product promise, legal claim, brand direction, or deleting existing content.
+- Group every blocking decision and missing capability into one question.
+- Retain every completed draft so a person reviews all changes before merge. Never request merge directly.
+- Discard only when no useful draft was produced or the attempted approach was fully abandoned.
+```
+
 When a run cannot continue correctly without a decision from a project member, it may call `ask_user` instead. The
 question goes to the Fimo Inbox, the current invocation ends, and Fimo keeps the same task Branch and environment until
 an authorized member answers. The answer starts one ordinary continuation in the same run thread; the original model
@@ -106,41 +151,49 @@ changes and finishes with `discard` and a brief report of what is waiting.
 
 Capabilities describe the opt-in Fimo and network actions an agent may take. Managed agents always receive project
 filesystem access, a shell, and the ability to commit their task-environment changes; Fimo owns branch creation and
-publication. If `capabilities.yaml` is absent or empty, the agent has those project-worker tools but no Fimo API
-permissions or web-fetch tool. Once you add a capabilities file, list every Fimo or network permission the agent needs.
-There is no all-capabilities wildcard; keeping the list explicit makes each agent's power reviewable.
-
-| Capability                   | Allows the agent to                         | Risk         |
-| ---------------------------- | ------------------------------------------- | ------------ |
-| `cms:read`                   | Read CMS content                            | Low          |
-| `cms:write`                  | Create, update, or delete CMS entries       | Medium       |
-| `cms:schema:read`            | Read CMS schemas                            | Low          |
-| `cms:schema:write`           | Modify CMS schemas                          | High         |
-| `assets:read`                | Read uploaded media                         | Low          |
-| `assets:write`               | Upload, replace, or delete media            | Medium       |
-| `i18n:read` / `i18n:write`   | Read / modify translation catalogs          | Low / Medium |
-| `forms:read` / `forms:write` | Read / modify form schemas and submissions  | Low / Medium |
-| `webhooks:read`              | Read webhook configs and deliveries         | Low          |
-| `webhooks:write`             | Create, modify, delete, or trigger webhooks | High         |
-| `schedules:read`             | Read schedule configs and run history       | Low          |
-| `schedules:write`            | Create, change, or trigger scheduled runs   | Critical     |
-| `fimo:logs:read`             | Read project deployment logs                | Low          |
-| `fimo:analytics:read`        | Read analytics data                         | Low          |
-| `fimo:preview:read`          | Read a current preview URL                  | Low          |
-| `fimo:history:read`          | Read project restore points                 | Low          |
-| `fimo:deploy`                | Trigger a production deploy                 | Critical     |
-| `net:fetch`                  | Make outbound HTTP requests                 | Medium       |
-| `agent:delegate`             | Invoke declared sub-agents                  | Medium       |
-| `runtime:long_running`       | Run beyond the default time limit           | High         |
-| `runtime:auto_merge`         | Auto-merge trivial proposed branches        | Critical     |
+publication. If `capabilities.yaml` is absent or empty, the agent keeps baseline project reads such as agent run history,
+but receives no CMS, asset, or other domain-operation scope and no web-fetch tool. Once you add a capabilities file,
+list every Fimo or network permission the agent needs.
+Namespace selectors such as `cms:*`, `assets:*`, `i18n:*`, and `forms:*` grant every current and future declarable capability
+in that namespace. Fimo expands selectors to concrete grants when a run starts. Use exact tokens for narrower agents.
+The default template includes those four selectors plus read access to analytics, deployment logs, history, previews,
+webhooks, and schedules; remove entries when an agent should have less access.
+
+| Capability                                  | Allows the agent to                                                       | Risk         |
+| ------------------------------------------- | ------------------------------------------------------------------------- | ------------ |
+| `cms:read`                                  | Read CMS content                                                          | Low          |
+| `cms:write`                                 | Create, update, or delete CMS entries                                     | Medium       |
+| `cms:schema:read`                           | Read CMS schemas                                                          | Low          |
+| `cms:schema:write`                          | Modify CMS schemas                                                        | High         |
+| `assets:read`                               | Read uploaded media                                                       | Low          |
+| `assets:write`                              | Upload, replace, or delete media                                          | Medium       |
+| `i18n:read` / `i18n:write`                  | Read / modify translation catalogs                                        | Low / Medium |
+| `cms:*` / `assets:*` / `i18n:*` / `forms:*` | Every declarable capability in that namespace, including future additions | Mixed        |
+| `forms:read` / `forms:write`                | Read / modify form schemas and submissions                                | Low / Medium |
+| `webhooks:read`                             | Read webhook configs and deliveries                                       | Low          |
+| `webhooks:write`                            | Create, modify, delete, or trigger webhooks                               | High         |
+| `schedules:read`                            | Read schedule configs and run history                                     | Low          |
+| `schedules:write`                           | Create, change, or trigger scheduled runs                                 | Critical     |
+| `fimo:logs:read`                            | Read project deployment logs                                              | Low          |
+| `fimo:analytics:read`                       | Read analytics data                                                       | Low          |
+| `fimo:preview:read`                         | Read a current preview URL                                                | Low          |
+| `fimo:history:read`                         | Read project restore points                                               | Low          |
+| `fimo:deploy`                               | Trigger a production deploy                                               | Critical     |
+| `net:fetch`                                 | Make outbound HTTP requests                                               | Medium       |
+| `agent:delegate`                            | Invoke declared sub-agents                                                | Medium       |
+| `runtime:long_running`                      | Run beyond the default time limit                                         | High         |
+| `runtime:auto_merge`                        | Auto-merge trivial proposed branches                                      | Critical     |
 
 If a public Fimo capability is missing and the work is genuinely blocked, the agent can request it through `ask_user`.
 Fimo grants only the selected subset to the next invocation in that run thread. Unknown capabilities, internal runtime
 abilities, and capabilities the run already holds are refused before the question is stored. For durable access on
 ordinary future runs, add the capability to `capabilities.yaml`, validate, and deploy the bundle.
 
-Studio chat and project-bound Slack turns receive `fimo:logs:read`. Autonomous agents receive it only when their
-`capabilities.yaml` declares it; use `fimo logs` with the deploy guidance when diagnosing a failed preview.
+Managed agents can list project agents and read their run history through baseline project access. This does not
+require `fimo:agents:run`; that capability is only required to dispatch another agent.
+
+Studio chat and project-bound Slack turns receive `fimo:logs:read`. The default autonomous-agent template now declares
+it too; custom templates still need to declare it before using `fimo logs` to diagnose a failed preview.
 
 Example for a content editor that can read and update entries but cannot change schemas:
 

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

@@ -56,6 +56,15 @@ Use the publication ID returned by the failed command: run `fimo publish inspect
 
 If the sandbox fails to install dependencies or start the app, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --before <cursor> --json` to fetch the preceding page. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
 
+When Preview reports blocked dependency build scripts, treat that as a project security-policy repair, not a transient sandbox failure. Review every named package before approving it, then use the package manager's narrow project-owned mechanism:
+
+- **pnpm:** add each approved package to `allowBuilds` in `pnpm-workspace.yaml`.
+- **Yarn:** set `dependenciesMeta.<package>.built` in `package.json` for each approved package.
+- **Bun:** add approved packages to `trustedDependencies` in `package.json`, or run the exact `bun pm trust <packages>` command Preview reports.
+- **npm:** npm has no equivalent per-package approval error. Diagnose the failing lifecycle script itself; do not turn a generic npm script failure into a trust-policy change.
+
+Run the same plain install locally and commit the policy plus lockfile before retrying Preview. Never bypass the error with `dangerouslyAllowAllBuilds`, `enableScripts`, or another global allow-all switch: Preview and publishing intentionally consume the committed project policy.
+
 ## Framework hosting
 
 Fimo preview resolves `runtime.commands` override → package script → detected

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

@@ -56,17 +56,17 @@ When a user says "I want to change my website's URL," ask which case fits:
 
 If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
 
-## Offer a cleaner default URL after first publish
+## Offer a cleaner default URL before first publish
 
-After the project's first successful `fimo deploy --publish`, offer a cleaner free `*.fimo.site` URL when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. This is not part of the automatic first preview. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
+After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
 
-The default URL is free and needs no DNS. A custom domain is the separate Premium workflow above. Renaming the default slug changes a public URL, so never silently claim a suggestion:
+The default URL is free and needs no DNS. A custom domain is the separate Premium workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
 
 1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
 2. Show the candidates and ask the user to choose one explicitly.
 3. After confirmation, run `fimo domains rename-default <slug>` or `fimo domains suggest-default --pick <slug>`.
 
-The renamed URL resolves after a successful publish.
+Choosing the slug does not publish the site. The first successful `fimo deploy --publish` makes the renamed URL resolve.
 
 ## Pricing & how money moves
 

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

@@ -15,6 +15,8 @@ fimo init [dir] [options]
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
+Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspace.yaml#strictDepBuilds: true` and `#allowBuilds` settings. Generated Bun projects trust the same required packages through `package.json#trustedDependencies`. Keep the selected package manager's policy committed. When adding a dependency with an install script, review it before extending that policy; never replace it with a blanket allow-all install.
+
 | Flag                         | Required                      | Purpose                                                                                                                                                        |
 | ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
@@ -163,6 +165,8 @@ fimo deploy -m "chore: first preview" --json
 
 This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
 
+After the preview succeeds, follow `references/domains.md` § Offer a cleaner default URL before first publish. Reserve a slug only after the user chooses it; the URL will not resolve until the site is published.
+
 ## Adding another AI tool to an existing project later
 
 If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:

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

@@ -104,7 +104,7 @@ These canonical entries are also the optional metadata used by Studio Pages. See
 
 For every framework, the application owns its URL scheme, resolves the locale, and passes it into Fimo. Studio stores the locale the app reports for the current location — including when only the locale changed — and reads content in it. Route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 
-Astro and Next express the same optional-locale semantic with paired native filesystem route trees: an unprefixed default-locale tree and a prefixed non-default tree. Neither framework supports an optional single-segment filesystem folder.
+Neither Astro nor Next supports an optional single-segment filesystem folder. Astro's starter expresses an optional-locale semantic with paired native filesystem route trees. The Next starter is default-only; a Next application adds a `[locale]` tree or another application-owned strategy only when the product requires locale URLs.
 
 ## Migrate An Existing Locale System
 

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

@@ -60,7 +60,7 @@ The Project MCP catalog covers:
 - **Identity and navigation** — current user, projects, and Branches.
 - **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
+- **Media** — list and inspect assets, read canonical pages or ask one targeted question with `assets_read`, 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 Branch. Sensitive files

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

@@ -159,11 +159,28 @@ Do not generate when:
 
 Upload real files with `fimo assets upload`. Browse reusable media with `fimo assets list` before spending credits.
 
+## Inspect an existing asset
+
+Open the original when visual or binary inspection is required. Read canonical text when exact portable understanding
+is required:
+
+```bash
+fimo assets open <asset-id> --download
+fimo assets read <asset-id>
+fimo assets read <asset-id> --cursor <next-cursor>
+fimo assets read <asset-id> --query "<one targeted question>"
+```
+
+For a complete exact read, keep following `nextCursor` until `complete` is `true`. Never combine `--cursor` and
+`--query`. Complete readable interpretation is lazy and cached, separately from compact Media Library alt/caption
+metadata. A 3D read includes four reusable rendered views. Download ZIP archives and inspect them in the sandbox; do
+not expect server-side extraction.
+
 ## Verification
 
 After generation:
 
 1. Confirm the command exited successfully and returned an asset ID.
-2. Open or download the asset with `fimo assets open <id>`.
+2. Open the original with `fimo assets open <id>`, or read its canonical understanding with `fimo assets read <id>`.
 3. Verify it matches the request before inserting it into content or UI.
 4. Use the whole media value with Fimo's `<Image>` or `<Video>` components rather than raw HTML elements.

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

@@ -23,6 +23,29 @@ Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must matc
 
 Required root keys: `uid`, `name`, and `fields`.
 
+## Group fields in Studio
+
+Use optional top-level `groups` when an entry has meaningful editing areas, such as Overview, Tickets, SEO, or Scheduling. They work best for longer forms where editors regularly work on one area at a time. Usually skip groups for short forms, one-field groups, or vague buckets such as General and Other. Prefer two to five groups organized around editor tasks. This is guidance, not a schema limit.
+
+Assign each top-level field with `group`; one field may appear in more than one group. This changes only the Studio layout, not stored content, generated types, validation, permissions, or what agents can edit.
+
+```json
+{
+  "uid": "Event",
+  "name": "Events",
+  "groups": [
+    { "id": "overview", "label": "Overview", "default": true },
+    { "id": "tickets", "label": "Tickets" }
+  ],
+  "fields": {
+    "title": { "type": "string", "group": "overview" },
+    "price": { "type": "number", "group": ["overview", "tickets"] }
+  }
+}
+```
+
+Group IDs must be unique, at most one group may be the default, and memberships must reference a declared group. Only top-level fields can be grouped; fields inside blocks cannot declare `group`.
+
 Use `"isSingleton": true` whenever the site has exactly one logical document: a homepage, site settings, an About page, or one campaign landing page. Do not turn it into a one-entry collection just to seed content; keep the Single and load `fimo-cli/references/content.md` for the `fimo singles update` workflow.
 
 ```json

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

@@ -35,13 +35,13 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 
 ## New-project boundary
 
-Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That edit is the whole locale setup: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider`, the `<html lang>` of each tree, and the set of prefixed URLs follow it. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
+Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That is content and provider configuration: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider` and the `<html lang>` follow it. It does not create locale URLs. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
 
-The starter keeps default routes in an unprefixed `app/(default)` route group and a native `app/[locale]` tree for the other locales. Only a root layout may render `<html>`, so each tree owns its root layout and renders the shared `src/components/Document.tsx` with its locale: the unprefixed tree with `defaultLocale`, the prefixed tree with `params.locale`. The prefixed layout 404s a locale that is not in `prefixedLocales`, which is why the default locale has exactly one URL. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned.
+The starter is default-only: one ordinary root layout renders `<html lang={defaultLocale}>` and `FimoProvider`, `/` is the homepage, and unknown paths get Next's native 404. Implement a locale routing strategy only when the product asks for one — prefixed `[locale]` segments, middleware, cookies, domains, or an i18n library are all Next decisions — then resolve the locale in that strategy and pass it into Fimo server reads and `FimoProvider`. Do not install a top-level `[locale]` route or an optional catch-all speculatively: it captures `/favicon.ico` and every unknown top-level path, and Fimo never requires it.
 
-Next.js has no optional single-segment route folder, so mirror localized routes in both existing groups as the site grows. Astro uses the same paired native filesystem-tree shape for this semantic. Do not replace the trees with middleware, rewrites, an optional catch-all that captures the application route tree, or a Fimo route helper. The config route catalog describes the URL shapes for Studio; Next's `app` directory remains authoritative.
+When the app implements a localized URL shape, describe it in `.fimo/config.json#routes` for Studio. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned. The config route catalog describes URL shapes for Studio; Next's `app` directory remains authoritative.
 
-Keep the starter's client-only `src/components/FimoPreviewBridge.tsx` inside `Document`, so both trees mount it. It reads Next's native pathname/router, reports the settled locale to Studio, and lets Studio navigate through Next; do not move Next imports into Fimo's shared runtime.
+`FimoProvider` owns the optional Studio preview runtime, including Next navigation and script loading. Application code only passes its resolved locale to the provider. Do not add a preview bridge component, read Fimo preview environment variables, or inject Fimo scripts.
 
 With `next-i18next`, keep its routing and translation provider for the strings it owns. Pass the same resolved locale to Fimo; do not replace the library or duplicate its route structure.
 

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

@@ -133,6 +133,7 @@ For new projects, apply `references/locales.md`, keep the starter's `:locale?` r
 ## Boundaries
 
 - Route modules and `meta` exports own routing and SEO.
-- `FimoScripts` owns preview-script loading; do not add the overlay script manually.
+- `FimoProviders` owns the optional Studio preview runtime. Do not read Fimo preview environment variables or inject its script in application code.
+- `FimoScripts` owns document-only JSON-LD and the development error overlay.
 - Use `fimo deploy` only when the developer requests a hosted preview or publication.
 - Load `references/ui.md` for rendering and `references/locales.md` for locale ownership.

package/assets/skills/fimo-code/references/frameworks/sveltekit.md

@@ -127,11 +127,9 @@ export const actions = {
 
 ## Live preview
 
-`FimoProvider` owns the Studio browser bridge. On mount it reads
-`PUBLIC_FIMO_PREVIEW_SCRIPT_URL` from SvelteKit's dynamic public environment,
-loads that script once, delegates navigation to SvelteKit's `goto`, and
-refreshes data with `invalidateAll()`. Without that environment value it does
-nothing. Do not add a second preview component.
+`FimoProvider` owns the optional Studio preview runtime, including script
+loading, SvelteKit navigation, and content refresh. Do not add a second preview
+component, read Fimo preview environment variables, or inject Fimo scripts.
 
 ## Boundaries
 

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

@@ -13,7 +13,7 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the framework-native route boundary and matcher, and the document language default. If the user gives no locale signal, retain the starter default and state that choice.
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the document language default, and any framework-native locale route boundary or matcher the application implements. If the user gives no locale signal, retain the starter default and state that choice.
 
 Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
@@ -45,4 +45,4 @@ For an already linked project, enable each locale in Fimo before writing non-def
 
 Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Every framework resolves its active locale and passes it to Fimo through that framework's provider or server-read seam.
 
-Astro and Next implement an optional locale boundary with paired native filesystem route trees: one unprefixed tree for the default locale and one prefixed tree for the other locales. Neither framework has an optional single-segment filesystem folder.
+Neither Astro nor Next has an optional single-segment filesystem folder; an optional locale boundary in those frameworks is paired native filesystem route trees, one unprefixed for the default locale and one prefixed for the others. The Astro starter ships that pair; the Next starter is default-only, so a Next application adds a `[locale]` tree (or another strategy) only when the product asks for prefixed URLs.

package/assets/skills/fimo-studio/references/billing-and-credits.md

@@ -57,10 +57,12 @@ From there:
 Some organizations that already have Premium may see a **Plan transition**
 section in Billing. It shows the recorded offer and the deadline to respond.
 
-- **Review the offer** opens the normal plan dialog with the exact recorded
-  terms. Accepting asks the billing provider to activate Pro immediately and
-  credit the unused part of the current Premium period. The plan changes only
-  after the provider confirms the new subscription.
+- **Review the offer** opens the plan dialog without charging anything.
+  Selecting Pro opens a final confirmation with the provider-calculated unused
+  Premium credit, amount charged now, next renewal date, and next renewal
+  amount. Fimo rechecks those figures before switching; if they changed, you
+  review and confirm the new amount. The plan changes only after the provider
+  confirms the new subscription.
 - **Move to Free instead** is an explicit choice. Premium remains active until
   the end of the current billing period, then the organization moves to Free.
 - An offer that is still being prepared, has expired, or has already been

package/assets/skills/fimo-studio/references/cms.md

@@ -83,6 +83,8 @@ Press **Alt+J** to move to the next entry or **Alt+K** to move to the previous o
 
 If a field is invalid, the editor keeps the change unsaved and pins a status bar below the header. Choose **Review issues** to jump to the first invalid field, then **Next issue** to move through the remaining fields. Collapsed blocks open automatically. Once every issue is fixed, the editor confirms that all fields are valid and resumes saving.
 
+Longer entry forms may have quiet field-group tabs below the header. Choose a group to focus on that part of the entry, or choose **All fields** for the complete form. Studio remembers the selected group for that content type during the browser session, and copied entry links preserve the active group. If validation finds a problem elsewhere, **Review issues** opens All fields before focusing it. Groups only change the editor view; they do not hide content from the API or restrict what the AI can edit.
+
 A field labelled with a padlocked globe is shared across languages: it holds one value for the whole entry, so editing it in any language changes it in all of them. Fields without that marker are per language and only affect the language you are editing. Hover the icon for the same explanation in context.
 
 ## Editing Text

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

@@ -35,6 +35,7 @@ You may see different overlays depending on what is happening:
 
 - **"Working"** -- A loading overlay (heading "Working", subtext "Getting your preview in motion...") while the preview is being prepared.
 - **Error overlay** -- Something went wrong. The overlay shows details about the issue, and the AI can often auto-fix it for you.
+- **"Some installed packages need approval"** -- Choose **Fix with Fimo** to send the complete repair context to the coding agent, or **Copy details** to handle it elsewhere. Review every named package, commit only trusted package-specific approvals, and retry Preview. Never replace the project policy with a blanket allow-all setting.
 - **First generation progress** -- When your project is being built for the first time, a progress overlay shows the current status.
 
 ## Switching Workspaces

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-22T15:14:06.125Z",
+  "bundledAt": "2026-08-23T14:49:49.653Z",
   "cliVersion": "0.20.0",
   "external": [
     "oxc-parser",