fimo 0.20.0 → 0.21.0-experimental.1

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

@@ -73,11 +73,11 @@ Never construct `FimoString`, `FimoRichText`, `FimoBoolean`, or `FimoMedia` manu
 
 Choose the framework surface:
 
-- Next Server Components and data functions → `fimo/next`
-- Next Client Components → `fimo/next/client`
-- React Router/Vite client → `fimo/ui`
+- Next Server Components and data functions → `fimo-next`
+- Next Client Components → `fimo-next/client`
+- React Router/Vite client → `fimo-react`
 - Astro pages → `fimo/astro/components`
-- Svelte components → `fimo/sveltekit/components`
+- Svelte components → `fimo-sveltekit/components`
 
 Load the framework reference before copying an example. Next server and client imports are deliberately separate so React Query/client code does not leak into server bundles. Astro uses native `.astro` components and does not require React.
 

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

@@ -76,11 +76,20 @@ the selected pinned CLI. Give workers the project id, environment, exact CLI
 invocation, and verification command. Generated `.fimo` JSON without a
 successful platform read is not initialization.
 
-For an existing non-empty application, reuse the CLI's real flow: create or
-select the Fimo project with `fimo init`, then run
-`fimo link <project-id> -C <target> --env <env>` and verify the data plane.
-`fimo migrate init <url> <dir>` is only usable when the target directory is
-empty or already linked.
+Pick the setup path from the evidence:
+
+- **Source-backed, same framework** — copy or `git worktree` the source into the
+  target directory first, then run `fimo link -C <target> --env <env>`
+  (`fimo link <project-id> -C <target> --env <env>` when the owner supplied an
+  id). Link creates or selects the project, keeps the source's code, framework,
+  git history, and `origin`, initializes a repository when the copy has none,
+  and adds only the Fimo dependency, `.fimo/project.json`, the `fimo` remote,
+  and `.fimo/config.json#runtime.framework`. It never overlays a template, so
+  the target must already contain the source.
+- **Empty target, or an explicit framework conversion** — `fimo init` with the
+  chosen `--framework`, or `fimo migrate init <url> <dir>` for a URL crawl.
+  Both refuse a non-empty target and write nothing when they refuse.
+
 If authentication, organization selection, project creation, environment
 resolution, linking, or the verification read fails, stop before workers and
 report the exact failed command and setup requirement.
@@ -134,8 +143,9 @@ report the exact failed command and setup requirement.
   Private APIs and CMSs require a user-provided export or a narrowly scoped
   server-side credential. Never read credentials from browser code or copy
   them into browser code, migration artifacts, or reports. Target-project
-  authentication does not grant source access. Missing access stops only that
-  data lane and becomes unresolved; never invent replacement content.
+  authentication does not grant source access. If the source API URL or access
+  is missing or unreachable, stop and ask the user for it; do not guess, replace
+  the content, or mark the lane complete.
 - Model content before page code. Generated JSON is not imported content.
 - Model editorial content Fimo-natively: blocks for structured or repeatable
   sections, richtext for rich bodies, references for categories, authors,
@@ -162,8 +172,9 @@ report the exact failed command and setup requirement.
 - Do not report completion until the QA gate passes or every failed check is
   present in the migration report.
 - Import through the data-plane commands and verify locally before deployment.
-  Propose one preview deployment after a successful run, but deploy or publish
-  only after an explicit user request.
+  Deployment is not QA evidence. After successful local QA, follow the
+  new-project or existing-project rule in Completion and deployment. Never
+  publish without an explicit user request.
 
 ## Orient and route
 
@@ -204,14 +215,16 @@ The target is its own Fimo project directory. The client source checkout is
 read-only evidence: never run setup inside it, never modify it, and never
 hand-write a `.fimo/project.json` marker to fake a link.
 
-`fimo migrate init` is the migration setup gate. For a source-backed migration
-it validates the target and CLI auth, then delegates project selection and
-creation to the standard `fimo init` flow (same options, no separate creation
-path), and returns a setup receipt covering auth, the target link, the
-migration directory, and readiness. It fails with a structured error when auth
-is missing, the target is missing or invalid, or the project or organization
-is inaccessible. Both forms need a real ID supplied by the owner — without
-one, stop with an unresolved owner action instead of inventing an ID:
+`fimo migrate init` is the setup gate for an empty target; a target that
+already holds the copied source is set up with `fimo link` instead (see
+Initialized target precondition). `fimo migrate init` validates the target and
+CLI auth, then delegates project selection and creation to the standard
+`fimo init` flow (same options, no separate creation path), and returns a setup
+receipt covering auth, the target link, the migration directory, and readiness.
+It fails with a structured error when auth is missing, the target is missing or
+invalid, or the project or organization is inaccessible. Both forms need a real
+ID supplied by the owner — without one, stop with an unresolved owner action
+instead of inventing an ID:
 
 - Link an owner-supplied (empty) project:
   `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
@@ -225,8 +238,8 @@ React Router scaffold.
 
 Setup scaffolds the target and pushes its initial commit; that is the only
 remote write it performs — it never pushes schemas, uploads assets, or imports
-entries. `fimo deploy` and `fimo publish` stay separate and are never run
-automatically (see Completion and deployment).
+entries. Setup itself never deploys or publishes; the one new-project preview
+deploy happens only after successful local QA (see Completion and deployment).
 
 ## Command surface
 
@@ -253,12 +266,16 @@ Commands that perform actual data writes, all requiring the linked target:
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
 - `fimo migrate init` (source-backed form): the project link/creation and
   initial commit push described above.
+- `fimo link`: project creation or selection plus the in-place adoption of a
+  copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
 
-1. Run `fimo migrate init` and inspect the initialized target before any worker
-   edits it. Choose the target framework through the same canonical option as
+1. Run the setup path from "Initialized target precondition" and inspect the
+   initialized target before any worker edits it. A `fimo link` adoption keeps
+   the source framework; the `fimo init` / `fimo migrate init` paths choose the
+   target framework through the same canonical option as
    `fimo init`: pass the detected source framework for a source-backed
    migration, the framework the user explicitly chose for a conversion, and —
    for a URL-only or rebuild migration — the framework the user selected (ask
@@ -276,15 +293,19 @@ Commands that perform actual data writes, all requiring the linked target:
    all structural target code, and must pass the framework gate in
    `references/workers/framework.md` before content data and code workers
    start. Worker prompts and worker reports are plain text.
-3. The content planner reads every content-bearing source and consumer, writes
-   and pushes complete schemas, and writes the content import payloads required
-   by the Fimo CLI. It records source items, consumers, batches, and unresolved
-   behavior in the text plan; it does not create a second orchestration format.
-4. Once the content plan is ready, upload every planned asset and patch its
-   target payload references. After the asset gate passes (and, in conversion
-   mode, the framework gate), run data workers per schema/locale. Start content
-   code workers only after their imported records read back successfully, so
-   they can prove real values render through the native Fimo APIs.
+3. The content planner reads every content-bearing source and consumer. When
+   content comes from an API, it traces the active application client and
+   retrieves the complete accessible dataset before pushing schemas. It then
+   writes complete schemas and import payloads, recording source items,
+   consumers, batches, and unresolved behavior in the text plan rather than a
+   second orchestration format.
+4. Each discovery lane reports active media in its own surface. After the
+   runtime/framework, routes/SEO, and content discovery receipts are terminal,
+   the coordinator performs one fan-in: combine and deduplicate them into the
+   complete media-obligation list. Give only that list to the media worker; do
+   not require a content-planner rescan. Once it returns every mapping, patch
+   code and payload consumers. Start data after the asset gate and content code
+   only after its imported records read back successfully.
 5. Fan in the workers' plain-text reports. Compare their claimed files with
    `git diff`, their Fimo writes with read-back CLI queries, and their source
    coverage with the content plan. Every source item must be migrated,

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -86,21 +86,18 @@ behavior in place; when one cannot be preserved, record an explicit gap with
 the affected routes instead of shipping pages that silently lost their share
 metadata.
 
-## Build-time and browser runtime
-
-The Next server runtime reads `FIMO_CONTENT_API_URL`; client components and
-generated client hooks read `NEXT_PUBLIC_FIMO_API_URL`. For a local production
-build or migration acceptance run, expose both names and point them at the
-same tenant content URL. `FIMO_API_URL` is the management/CLI API and is not a
-substitute for either content API variable.
-
-`withFimo` derives these aliases during `next dev` when the project is linked,
-so local development does not need hand-written values. A production build,
-however, compiles `NEXT_PUBLIC_*` values into the browser bundle and the
-adapter intentionally does not inject them outside the development phase.
-For `next build`/`next start`, set temporary values in the shell or an ignored
-`.env.local`; never commit secret values. In either mode, exercise at least one
-client-side data read after startup.
+## Fimo connection
+
+Follow the target project's `fimo-code` Next.js reference and render its
+`FimoProvider` once at the application root. The provider uses an explicit
+host connection when one exists; otherwise it resolves the linked project and
+active git branch on the server and passes only the public connection to the
+browser. `withFimo` handles hosted preview origins, not the application
+connection.
+
+Do not create or edit `.env` / `.env.local` for a linked project's Fimo
+connection. Run the project's normal `next dev`, `next build`, and `next start`
+commands, then exercise at least one server read and one client-side data read.
 
 ## Preview embedding and response headers
 

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

@@ -94,12 +94,16 @@ If a media asset cannot be downloaded or uploaded:
 - include a suggested action such as re-exporting the asset folder or providing
   credentials
 
-## Planner obligations
-
-The content planner enumerates every media obligation before fan-out: route and
-SEO media, every schema media field, and every image node nested in richtext or
-Tiptap JSON. Record its source location, consuming route/entry, and intended
-target field or node. Give each obligation a stable identity that includes its
-field or rich-text node path; a shared label or source URL is not unique. The
-asset worker cannot report complete until every obligation has an uploaded or
+## Media obligations
+
+Each discovery lane reports active media in its own surface: runtime/framework
+files, routes and SEO, or content and API data. After every discovery receipt is
+terminal, the coordinator combines and deduplicates those findings into the
+complete media-obligation list. This consolidated list is the media worker's
+only input; do not make the content planner rescan the whole application.
+
+Record each obligation's source location, consuming route/entry, and intended
+target field or node. Give it a stable identity that includes its field or
+rich-text node path; a shared label or source URL is not unique. The media
+worker cannot report complete until every obligation has an uploaded or
 duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.

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

@@ -44,9 +44,10 @@ items.
 - Every media item referenced by routes, CMS entries, SEO, or forms is uploaded to
   the Fimo media library (Fimo asset id/URL) or has an unresolved item. A local
   `public/` copy is not an upload mapping.
-- Every planner media obligation, including schema media fields and nested
-  richtext/Tiptap image nodes, has a mapping or explicit disposition; the asset
-  worker's completion claim alone is not evidence.
+- Every obligation in the coordinator's consolidated media list, including
+  schema media fields and nested richtext/Tiptap image nodes, has a mapping or
+  explicit disposition; the media worker's completion claim alone is not
+  evidence. Reconcile the list against every discovery lane's media findings.
 - Every visible form has a Fimo replacement, a preserved third-party
   integration, or an unsupported note. A form became Fimo-native only when the
   Fimo form matches the source behavior 1:1.
@@ -85,11 +86,11 @@ items.
   used a user export or narrowly scoped server-side credential. Missing access
   is unresolved for that lane, and no content was guessed.
 
-For linked Next.js targets, `withFimo` derives `FIMO_CONTENT_API_URL` and
-`NEXT_PUBLIC_FIMO_API_URL` from `.fimo/project.json` during `next dev`,
-`next build`, and `next start`. Both aliases resolve to the same tenant API,
-while non-empty user overrides remain untouched; no committed env file is
-required.
+For linked Next.js targets, the root `FimoProvider` resolves an explicit host
+connection first, otherwise `.fimo/project.json` plus the active git branch,
+and passes only the public connection to the browser. `withFimo` handles
+hosted preview origins, not this connection. Run the normal `next dev`,
+`next build`, and `next start` commands without creating a Fimo env file.
 
 ## Hosting
 
@@ -103,9 +104,9 @@ Owned by the runtime lane; verified here read-only.
   translation goes through `FIMO_PREVIEW_ALLOWED_ORIGINS`; `withFimo` alone
   does not solve headers — it only extends `allowedDevOrigins` during
   `next dev`.
-- The runtime report covers local startup, preview embedding, build, derived
-  aliases, header translations, and integration env-key names, with every
-  claim backed by evidence.
+- The runtime report covers local startup, preview embedding, build, the
+  resolved Fimo connection, header translations, and integration env-key
+  names, with every claim backed by evidence.
 - With a browser available, record `browserProof` (rendered route plus console
   state) for startup and embedding. Without one, use deterministic HTTP
   status/header/process/log checks and mark visual proof explicitly

package/assets/skills/fimo-migration/references/workers/content-planner.md

@@ -5,9 +5,8 @@ handoff. Do not import entries or rewrite application consumers.
 
 1. Inspect every content-bearing source and consumer: Markdown/MDX bodies and
    frontmatter, JSX/TSX modules, hardcoded arrays and objects, imports, data
-   clients, and call sites. Read local exports and public APIs directly. A
-   private API requires a user-provided export or narrowly scoped server-side
-   credential; never recover or copy secret values.
+   clients, and call sites. Identify whether each active source is a file,
+   inline value, API, CMS, or a mix before designing schemas.
 2. Classify each value as collection content, single content, an
    editor-visible label, or application-owned code. Repetition is evidence,
    not an automatic collection rule. Assistive text, identifiers, and values
@@ -54,11 +53,41 @@ A construct is unresolved only when it genuinely cannot be migrated. Include
 its exact source, user-visible impact, reason, and owner action; "custom" is not
 a reason.
 
+## API-backed content
+
+Retrieve API content during this planning pass, before schemas are pushed or
+data workers start:
+
+1. Trace the application's active client, base-URL environment key, endpoints,
+   queries, pagination, locales, publication states, relations, media, and
+   consuming call sites. Server rendering may hide requests from the browser,
+   so browser traffic is fallback evidence rather than the source of truth.
+2. Prove access with one read-only request. Read public APIs directly. Private
+   APIs require an owner-provided export or narrowly scoped server-side
+   credential; never recover, log, persist, or copy secret values. If the base
+   URL or required access is missing or unreachable, stop and ask the user for
+   it before planning schemas or payloads.
+3. Fetch every required page, locale, and referenced record. For a few bounded
+   endpoints, direct requests are enough. For repeated or paginated reads,
+   write a temporary source-specific read-only script under
+   `.fimo/migration/tmp/`, then spot-check counts and references.
+4. Preserve the retrieved responses as source evidence and payload inputs;
+   normalize transport details only. Do not create a provider registry or a
+   universal CMS model.
+5. Design Fimo schemas from both the retrieved values and the code that uses
+   them. Never invent replacement content when source access is unavailable.
+
+Once retrieval and consumer tracing are complete, push schemas, prepare
+payloads, and let the coordinator fan out assets and one data batch per
+schema/locale. Runtime, routes, locales, and other independent workers continue
+in parallel while retrieval runs.
+
 ## Optional extraction helpers
 
 Start with `rg` and targeted reads. A bounded read-only helper under
 `.fimo/migration/tmp/` may parse repeated frontmatter, JSON/YAML exports, or
-literal structures while preserving source locations. Spot-check its output.
+literal structures, or retrieve repeated API pages while preserving source
+identities. Spot-check its output.
 The agent still owns classification, schema design, and consumer tracing. Do
 not build a generic codemod system or let the helper write Fimo data or app
 code.

package/assets/skills/fimo-migration/references/workers/validator.md

@@ -19,6 +19,16 @@ Verify:
 - build and representative browser interactions pass; and
 - every unsupported item names its impact and owner action.
 
+`fimo deploy` readiness proves only that the server stays up and a
+representative page responds. After an approved deploy, browser QA must:
+
+- open one representative route per route family and exercise one key interaction;
+- fail on route `5xx`, blank or reloading pages, or required module, API, or runtime failures;
+- inspect browser evidence and `fimo logs --json` before editing; and
+- run at most one focused repair and redeploy, then report remaining failures unresolved.
+
+Optional development-tool failures do not fail a rendered, stable application.
+
 Return a plain-text report with status, duration, checks run, counts, failing
 source items, and suggested bounded repair surface. The coordinator may run one
 repair for that surface and rerun validation. It does not restart every worker

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

@@ -19,7 +19,7 @@ Plan a lane only when the source proves that surface exists:
 | routes          | route modules, redirects, SEO and host behavior | immediately              |
 | content planner | schemas, content payloads, and content handoff  | immediately              |
 | locales         | locale setup and translated UI copy             | immediately              |
-| assets/forms    | media uploads and form behavior                 | after content planner    |
+| assets/forms    | media uploads and form behavior                 | after discovery fan-in   |
 | content data    | one schema/locale import                        | after assets             |
 | content code    | listed consuming files                          | after its data read-back |
 | validator       | read-only final checks                          | after all writers        |
@@ -35,15 +35,19 @@ read-back.
 - **runtime** preserves the detected framework, router, runtime, dependencies,
   provider setup, environment wiring, and provider-specific configuration. An
   unclear or unsupported setup produces a question, not a silent conversion.
+  It reports active media found in its surface.
 - **routes** preserves every route, redirect, 404, SEO/OG/social output,
   sitemap, robots, feeds, headers, and other observable host behavior. A file
-  that consumes migrated content belongs to its later content-code worker.
+  that consumes migrated content belongs to its later content-code worker. It
+  reports active route and SEO media.
 - **content planner** discovers and models all editable content, labels,
-  consumers, schemas, payloads, media obligations, and execution batches. It
-  never imports entries or rewrites consumers. Read
+  consumers, schemas, payloads, media in its content/API surface, and execution
+  batches. It first retrieves any API-backed source through the application's
+  real client contract; it never imports entries or rewrites consumers. Read
   `references/workers/content-planner.md`.
-- **assets/forms** uploads every planner media obligation and patches payload
-  references. It replaces a form or integration only when Fimo preserves its
+- **assets/forms** receives only the coordinator's consolidated, deduplicated
+  media-obligation list, uploads it, and returns mappings for code and payload
+  consumers. It replaces a form or integration only when Fimo preserves its
   behavior end to end; otherwise it preserves or reports it.
 - **content data and code** execute the planner handoff without rediscovering
   or redesigning it. Read `references/workers/content-execution.md`.
@@ -62,12 +66,17 @@ other after it. Do not add a metadata format for a small overlap.
    write.
 2. Start runtime/routes/content-planner/locales together, or the framework
    worker plus content planner/locales in conversion mode.
-3. After the content plan, upload every planned asset and patch payloads.
-4. Start data workers only after the asset gate and, in conversion mode, the
+3. Wait for every discovery receipt to become terminal, then perform one fan-in
+   of runtime/framework, routes/SEO, and content media findings. Combine and
+   deduplicate them into the complete media-obligation list; do not run another
+   discovery pass.
+4. Give only that consolidated list to assets/forms. Wait for its mappings
+   before code or payload consumers replace source references.
+5. Start data workers only after the asset gate and, in conversion mode, the
    framework gate.
-5. Start each code worker only after its own imported records read back as
+6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-6. Start the independent validator only after every writer has returned.
+7. Start the independent validator only after every writer has returned.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source

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

@@ -45,8 +45,16 @@ Classify the available evidence:
 
 For private APIs or CMSs, ask for a user-provided export or a narrowly scoped
 server-side credential. Never recover credentials from browser bundles or copy
-them into migration artifacts. Missing access blocks only that lane and becomes
-an unresolved item; never invent replacement content.
+them into migration artifacts. If the source API URL or access is missing or
+unreachable, stop and ask the user for it; do not guess or continue with
+replacement content.
+
+For API-backed content, trace the active client and call sites in source code,
+prove one read, then retrieve all required pages, locales, relations, and media
+during content planning. Use direct requests for bounded endpoints or a
+temporary read-only script for repeated and paginated reads. Do not wait for
+schema or code workers, and do not rely on browser traffic when SSR or build
+time fetches may hide the requests.
 
 For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
 generated `.fimo/migrations/current/` files as source evidence. Do not copy
@@ -58,16 +66,18 @@ The coordinator launches only the workers supported by the source:
 
 - **runtime**: preserve the detected framework, router, runtime, dependencies,
   provider configuration, and environment wiring. A framework conversion needs
-  an explicit user choice.
+  an explicit user choice. Report active media found in this surface.
 - **routes/SEO**: preserve one target route per source route, redirects, 404,
   metadata, OG/social output, sitemap, robots, and other observable behavior.
+  Report active media found in this surface.
 - **content planner**: discover content, labels, data sources, consumers, and
   schemas; push schemas and prepare content payloads. It does not rewrite page
-  code or import every entry itself.
+  code or import every entry itself. Report active media found in content and
+  API data; do not rescan unrelated runtime or route surfaces.
 - **locales**: configure locales and migrate translated UI-visible copy when
   the source has it.
-- **assets/forms**: after content planning, upload every referenced media item
-  and preserve, replace, or report forms and integrations.
+- **assets/forms**: after the discovery fan-in, upload the consolidated media
+  obligations and preserve, replace, or report forms and integrations.
 
 When the user explicitly chose a framework conversion, one framework
 conversion worker replaces the runtime and routes lanes and owns all
@@ -82,17 +92,22 @@ Workers may write the application inside their ownership. They do not need a
 JSON plan or receipt. If two workers need the same file, name one owner and run
 the other after it.
 
-## Phase 3: Content planning
+## Phase 3: Discovery fan-in and content planning
 
 The planner follows `references/workers/content-planner.md`, plus
 `references/content.md`, `references/decision.md`, and
 `references/import-contract.md`. Its text plan and payloads must be complete
-before Phase 4; data workers must not rediscover unrelated source files.
+before Phase 4; this includes retrieving API-backed source data and tracing its
+consumers. Data workers must not rediscover unrelated source files.
+
+After the runtime/framework, routes/SEO, and content discovery receipts are all
+terminal, the coordinator combines and deduplicates their media findings into
+the complete media-obligation list. This is the media worker's only input.
 
 ## Phase 4: Media, forms, and integrations
 
-1. Account for every planner media obligation, including schema media fields
-   and richtext/Tiptap image nodes, plus route, SEO, and form media.
+1. Account for every consolidated media obligation, including schema media
+   fields and richtext/Tiptap image nodes, plus route, SEO, and form media.
 2. Upload media through Fimo and replace references only after the upload is
    confirmed. A local `public/` copy or source URL is not an imported asset.
 3. Preserve third-party integrations unless Fimo reproduces their exact
@@ -139,4 +154,7 @@ Use `complete` only when required checks pass, `complete-with-unresolved` when
 the app works and every gap is explicit, and `draft-only` when import or
 verification is incomplete.
 
-All checks are local. Do not deploy or publish to verify a migration.
+All checks are local. Deployment is not QA evidence. After successful local QA,
+run one plain `fimo deploy` for a newly created project unless the user opted out
+or `FIMO_MIGRATION_NO_DEPLOY=1`; for an existing linked project, offer deploy and
+wait for approval. Never publish automatically.

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

@@ -22,7 +22,7 @@ Give the AI more to work with:
 - **+ button**: Opens a dropdown with options:
   - **Attach Assets** -- browse your media library and attach files.
   - **Attach Entries** -- attach CMS content for the AI to reference.
-  - **Upload from Computer** -- upload a file directly. ZIP archives are supported up to 20 MiB; the AI can download and inspect them under `/tmp` in its sandbox while the original stays attached to the conversation.
+  - **Upload from Computer** -- upload a file directly. For GLB, self-contained glTF, FBX, OBJ, STL, and PLY models, Fimo renders four views and saves a description so every chat model can understand the attachment. ZIP archives are supported up to 20 MiB; the AI can download and inspect them under `/tmp` in its sandbox while the original stays attached to the conversation.
   - **Draw** -- opens the drawing tool where you can sketch a wireframe or layout idea for the AI to follow.
 - **@ mentions**: Type **@** in the chat to reference specific files, pages, or content inline.
 

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

@@ -48,6 +48,23 @@ You can upgrade from two places:
 From there:
 
 1. Compare the available plans side by side.
-2. Premium plans include more monthly credits, custom domain support, and the ability to hide the Fimo badge on your published site.
+2. Pro includes more monthly credits, custom domain support, and the ability to hide the Fimo badge on your published site.
 3. Pick a plan and complete checkout.
 4. Your new monthly credit pool is available right away.
+
+## Legacy plan transitions
+
+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 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
+  resolved is shown as a status without an accept action. Silence never
+  accepts a price change.

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/assets/starters/fimo-site/template/src/pages/Contact.tsx

@@ -1,4 +1,4 @@
-import { type FimoString, Text, useLabels } from 'fimo/ui';
+import { type FimoString, Text, useLabels } from 'fimo-react';
 import { ArrowUpRight, Check } from 'lucide-react';
 import { type FormEvent, type ReactNode, useState } from 'react';
 

package/assets/starters/fimo-site/template/src/pages/SiteContent.tsx

@@ -1,4 +1,4 @@
-import { RichText, Text, useLabels } from 'fimo/ui';
+import { RichText, Text, useLabels } from 'fimo-react';
 import { ArrowDown, ArrowUpRight } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';

package/assets/starters/fimo-site/template/src/schemas/HomePage.ts

@@ -1,8 +1,8 @@
 // AUTO-GENERATED by `fimo` from src/schemas/HomePage.json - DO NOT EDIT.
 // Change content fields in the schema, then run `fimo validate`.
-// Runtime implementation lives in the project-local fimo/ui package.
-import { createSingletonClient } from 'fimo/ui';
-import type { ContentSchema, SingletonContentClient } from 'fimo/ui';
+// Runtime implementation lives in the project-local fimo-react package.
+import { createSingletonClient } from 'fimo-react';
+import type { ContentSchema, SingletonContentClient } from 'fimo-react';
 
 import schema from './HomePage.json';
 import type { HomePage, HomePageInput } from './HomePage.types';

package/assets/starters/fimo-site/template/src/schemas/HomePage.types.ts

@@ -11,7 +11,7 @@ import {
   type Sort,
   type Where,
   type WithReferences,
-} from 'fimo/ui';
+} from 'fimo-react';
 
 export interface HomePageFimoMeta {
   contentType: string;

package/dist/build/astro/config.d.ts

@@ -1,4 +1,15 @@
 import type { AstroIntegration } from 'astro';
-/** Connect an Astro app to Fimo preview and hosted server rendering. */
-export declare function fimo(): AstroIntegration;
+export interface FimoAstroConfigOptions {
+    /**
+     * Hosting adapter registered for `output: 'server'` builds that declare no
+     * adapter of their own. Supplied by `fimo-astro/config`; `fimo` itself ships
+     * no provider so non-Astro projects never install one (FIMO-1635).
+     */
+    hostingAdapter?: AstroIntegration;
+}
+/**
+ * Connect an Astro app to Fimo preview and the git branch's Fimo env.
+ * Server-rendered Fimo hosting needs the adapter from `fimo-astro/config`.
+ */
+export declare function fimo(options?: FimoAstroConfigOptions): AstroIntegration;
 //# sourceMappingURL=config.d.ts.map