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

package/assets/skills/fimo/SKILL.md

@@ -17,6 +17,10 @@ When you are about to do Fimo work:
 1. List what's available: `npx fimo@latest skills list`
 2. Load the relevant skill: `npx fimo@latest skills get <name>` (add `--ref <doc>` for a reference doc)
 
+Reference paths mentioned in streamed skill output, such as `references/media.md`, are identifiers,
+not files in the project. Load them through the CLI, for example
+`npx fimo@latest skills get fimo-cli --ref media`. Do not use a filesystem read tool for them.
+
 Pick by task:
 
 - Writing code — schema-driven JSX, schemas/forms JSON, `t()` labels, `fimo/ui` media → `fimo-code`

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

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

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

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

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

@@ -33,6 +33,14 @@ To halt the AI mid-generation, use the **Stop button** in the input bar — whil
 
 While the AI works, you see small badges in the chat showing what it is doing. Each badge displays a tool name and its current status. Examples include reading files, writing code, searching your project, or generating images. These badges help you follow along without needing to understand the technical details.
 
+## Reviewing Changes That Could Not Merge
+
+Chat changes are prepared separately and then applied to the environment you are viewing. Most changes merge automatically.
+
+If the project changed in the same place while the AI was working, the response shows a **Review changes** card 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.
+
+Discarding the merge leaves the current environment unchanged and keeps the proposal separate.
+
 ## Tips for Better Results
 
 - **Be specific**: Mention colors, layout, text content, and spacing when you can.

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

@@ -16,6 +16,12 @@ To push your latest changes live, open the publish panel from the header **Publi
 
 > **Tip:** Before your site has ever been published, the chat shows a one-click **Publish** button that deploys immediately without opening the panel.
 
+## Publishing Changes That Need Review
+
+If an AI chat change cannot merge automatically, use the response's **Review changes** card first. Resolve the conflicts and merge the proposal into `main`.
+
+When the AI requested publication, the review dialog offers **Merge and publish** after the conflicts are resolved. Publishing starts only after the merge succeeds, so unresolved or discarded proposals never reach the live site.
+
 ## What You See When You Click Publish
 
 The header **Publish** button itself only shows the label "Publish" (or a spinner while a deploy is running). Open the panel to see the current state:

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-28T17:34:40.817Z",
+  "bundledAt": "2026-07-30T16:52:56.741Z",
   "cliVersion": "0.10.0",
   "external": [
     "oxc-parser",