fimo 0.17.0 → 0.18.0

package/assets/astro/components/DateTime.astro

@@ -0,0 +1,22 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: globalThis.Date | String | string | number | null | undefined;
+  locale?: string;
+  options?: Intl.DateTimeFormatOptions;
+  [key: string]: unknown;
+}
+
+const { value, locale, options, ...props } = Astro.props;
+const rawValue = value instanceof String ? value.toString() : value;
+const date = rawValue == null ? null : new globalThis.Date(rawValue as string | number | globalThis.Date);
+const validDate = date && !Number.isNaN(date.getTime()) ? date : null;
+// The whole instant, not just the day: a `datetime` field exists to name a
+// moment, and truncating it here would throw the time away on every page.
+const dateTime = validDate?.toISOString();
+const content = validDate?.toLocaleString(locale, options ?? { dateStyle: 'medium', timeStyle: 'short' });
+const source = getFimoSource(value);
+---
+
+{validDate && <time {...props} datetime={dateTime} data-fimo-source={source}>{content}</time>}

package/assets/astro/components/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

package/assets/astro/components/index.js

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

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

@@ -97,6 +97,7 @@ function getTypeForField(field) {
     case 'boolean':
       return 'FimoBoolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, any>';
@@ -126,6 +127,7 @@ function getInputTypeForField(field) {
     case 'boolean':
       return 'boolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, unknown>';

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

@@ -15,7 +15,7 @@ This skill describes **what the CLI does and the workflows it drives**. For the
 
 Use `fimo <command> --help` for full flag details on any command.
 
-> **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
+> Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
 ## Running the CLI
 
@@ -75,7 +75,8 @@ Keep `fimo validate --json` at the front of the project's `build` script, which
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
 - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**

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

@@ -2,12 +2,12 @@
 
 > Package contract: load the version-locked `fimo-code` skill with `fimo skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
 
-This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
+This file covers the **CLI workflow** for content schemas, Singles, and entries. Use it when the user wants to add a content type (blog, products, reusable content) or manage content records. For route metadata shown in Studio Pages, load `references/pages.md`.
 
 ## Choose the write path first
 
 - Exactly one homepage, settings document, About page, or campaign page → declare `"isSingleton": true` and write it with `fimo singles update <TypeName>`.
-- Repeated posts, products, team members, or reusable pages → keep a collection and create rows with `fimo entries create <TypeName>`.
+- Repeated posts, products, team members, or other reusable records → keep a collection and create rows with `fimo entries create <TypeName>`.
 
 Never remove `isSingleton: true` merely because `fimo entries create` rejects the type. `entries` and `singles` are separate command namespaces; inspect `fimo singles --help` when the content is one-off.
 

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

@@ -118,6 +118,8 @@ curl -H 'Accept: text/markdown' https://your-site/  # content negotiation
 curl https://your-site/?format=md                # query param
 ```
 
+This is a hosting capability: Fimo generates the `.md`, content-negotiation, and `?format=md` responses for supported built pages. Application code must not reimplement any of them — in particular, never add a route that fetches the app's own public URL to convert it to Markdown. For a dynamic page, render Markdown from the same server-side data the page itself uses when the framework supports that; otherwise report the capability as unresolved instead of building a self-fetching route.
+
 ## Recovering from Git drift
 
 Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:

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

@@ -72,9 +72,16 @@ fimo init my-svelte-site --framework sveltekit --org <organizationId>
 ```
 
 Each shell includes its framework adapter, hosted-preview connector, and
-`.fimo/config.json#runtime.framework`. The Astro shell also includes a minimal
-content-backed example with static, on-demand, and dynamic routes plus an English default locale;
-the other shells intentionally contain no schema, labels, or designed website.
+`.fimo/config.json#runtime.framework`, plus an application-owned optional locale
+boundary that keeps the default locale unprefixed. The Astro shell also includes a minimal
+content-backed example with static, on-demand, and dynamic routes; the other shells intentionally
+contain no schema, labels, or designed website.
+
+Set the primary locale from the request: when several are explicitly named, use the first as default;
+if none is requested, keep `en` and tell the user. Update `.fimo/config.json#i18n`, the framework-native
+locale boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts
+there. Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless
+the site needs them.
 After init, load the project rules and `fimo-code` to build the requested site.
 If you replace a shell's code with a site that uses another framework or none,
 fix `runtime.framework` in the same change
@@ -93,7 +100,7 @@ Pass `--project-id <id>` to set up a known Fimo project. If the project has no c
 
 - The selected project shell: React Router by default, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
-- `.fimo/config.json` — project, route, locale, SEO, and agent policy
+- `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
 - `.env` — framework-specific tenant content API URLs for local development
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.

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

@@ -19,17 +19,13 @@ These commands update the selected Branch through the locale lifecycle API. The
 
 If a mutation exits with code `2` and `data.code` is `LOCALE_APPLIED_SYNC_REQUIRED`, the remote operation succeeded (`data.applied` is `true`) but the local fast-forward did not. **Do not retry the locale command.** Run the commands in `data.sync.recovery`, resolve the checkout, and confirm with `fimo status` or `fimo locales list`.
 
-Edit `.fimo/config.json` only for declarative routing behavior:
+Edit `.fimo/config.json` only for declarative locale and route metadata:
 
 ```jsonc
 {
   "i18n": {
     "defaultLocale": "en",
     "locales": ["en"],
-    "routing": {
-      "strategy": "path-prefix", // only supported strategy: /es/about for Spanish; default locale can stay /about
-      "prefixDefaultLocale": false, // when false, omit /en for the default locale
-    },
   },
 }
 ```
@@ -37,7 +33,7 @@ Edit `.fimo/config.json` only for declarative routing behavior:
 - `defaultLocale` is the locale used by `fimo validate`, `fimo labels set` without `--locale`, and content commands without `--locale`. Change it with `fimo locales set-default`.
 - `locales` must include `defaultLocale`. Add and remove values with `fimo locales add` and `fimo locales remove`.
 - Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
-- `routing.strategy` currently supports `path-prefix`.
+- New projects do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
 `fimo locales remove` permanently deletes that locale's stored entries and labels.
@@ -55,38 +51,66 @@ Validation checks:
 - malformed locale tags
 - `defaultLocale` missing from `locales`
 - unsupported routing strategies
-- canonical routes in `.fimo/config.json` that claim reserved locale prefixes, for example `/es`
-- top-level dynamic routes that could capture locale prefixes unless the project uses Fimo's React Router helper
+- routes in `.fimo/config.json` that hardcode a locale prefix, for example `/es/pricing`
+- two routes that answer the same URL once the locale segment is removed
+- a `:locale` segment that is not first, or that declares `schema`, `queryField`, `displayField`
+- an entry param declared `optional`, or missing `schema` / `queryField`
+- top-level dynamic routes other than `:locale` that could capture locale prefixes
 - missing default-locale DB labels
 
 ## Route Metadata Rule
 
-Keep `.fimo/config.json#routes` canonical and unlocalized:
+Write the locale into a route's path with the reserved `:locale` segment, never as a literal prefix. The descriptor `type` is optional: `locale` infers `"locale"`, while every other parameter defaults to `"entry"`:
 
 ```json
 {
   "routes": {
+    "blog-post": {
+      "label": "Blog post",
+      "path": "/:locale/blog/:slug",
+      "params": {
+        "locale": { "type": "locale", "optional": true },
+        "slug": { "schema": "BlogPost", "queryField": "slug", "displayField": "title" }
+      }
+    },
     "pricing": {
       "label": "Pricing",
-      "path": "/pricing"
+      "path": "/:locale/pricing",
+      "params": { "locale": { "type": "locale", "optional": true } }
     }
   }
 }
 ```
 
-Do not add `/es/pricing` as a second Fimo route. The route selector localizes canonical routes for the active preview locale. In React Router projects, use the package helper:
+| Declared path         | `params.locale`                           | URLs the route answers                              |
+| --------------------- | ----------------------------------------- | --------------------------------------------------- |
+| `/:locale/blog/:slug` | omitted                                   | `/blog/hello` for `en`, `/fr/blog/bonjour` for `fr` |
+| `/:locale/blog/:slug` | `{ "type": "locale", "optional": false }` | `/en/blog/hello` and `/fr/blog/bonjour`             |
+| `/:locale/pricing`    | omitted                                   | `/pricing` for `en`, `/fr/pricing` for `fr`         |
+
+- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is content-backed and needs both.
+- `optional: true` means omit the configured default locale from the URL. With `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French.
+- `optional: false` prefixes every locale, including the default (`/en/pricing` and `/fr/pricing`). Changing `i18n.defaultLocale` chooses the fallback locale; it does not by itself change this prefix policy.
+- A route with no `:locale` segment stays application-owned. Studio shows it once and neither adds nor interprets a locale segment.
+- Do not add `/es/pricing` as a second route. A locale segment does not make two routes distinct.
+
+Register the same shape in the router. React Router spells the omittable segment `:locale?`:
 
 ```ts
-import { fimoRoutes } from 'fimo/react-router/routes';
+route(':locale?/blog/:slug', './pages/BlogPost.tsx');
 ```
 
-For every framework, the application owns its URL scheme and passes the resolved locale into Fimo. Canonical route metadata is optional unless the project wants Fimo Studio route selection/navigation.
+These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for content-backed `params` and declared `sources`.
+
+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.
 
 ## Migrate An Existing Locale System
 
 Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
 
-Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
+Preserve the existing locale provider, router, switcher, redirects, and public URLs. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference and its focused route-ownership migration when upgrading; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
 
 ## Labels And Content
 

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

@@ -0,0 +1,70 @@
+# Pages route metadata
+
+Pages can mirror the application's routes in Fimo Studio. It gives editors a route tree and, for each selected route, a page-shaped workspace for its Labels, Single, bound entries, and Collection results. The CLI writes this optional metadata to `.fimo/config.json` under `routes.<id>`; it does not replace the application router or move or duplicate content.
+
+## Route shape
+
+A route has three separate parts:
+
+- `path` is the URL pattern, such as `/blog/:slug`.
+- `params` optionally binds path placeholders to Collection entries so Studio can select a concrete route in the page header.
+- `sources` optionally names the Labels, Single, and Collection results editors manage after selecting a route.
+
+Each param key matches a `:placeholder` in `path`. `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
+
+```bash
+fimo pages set <id> --path '/shop/:category/:product' --params '{"category":{"schema":"Category","queryField":"slug","displayField":"name"},"product":{"schema":"Product","queryField":"slug","displayField":"name","query":{"where":{"category":"$params.category.id"},"sort":"name"}}}'
+```
+
+`sources` is a named object under `routes.<id>.sources`. It is not an array or a route definition. Keep its keys stable and descriptive:
+
+```json
+{
+  "copy": {
+    "type": "labels",
+    "match": ["blog.*"]
+  },
+  "settings": {
+    "type": "single",
+    "schema": "BlogSettings"
+  },
+  "relatedPosts": {
+    "type": "collection",
+    "schema": "BlogPost",
+    "query": {
+      "where": {
+        "category": "$params.slug.category"
+      },
+      "sort": "-publishedAt",
+      "limit": 4
+    }
+  }
+}
+```
+
+Pass that same object as JSON:
+
+```bash
+fimo pages set <id> --sources '{"copy":{"type":"labels","match":["blog.*"]},"settings":{"type":"single","schema":"BlogSettings"},"relatedPosts":{"type":"collection","schema":"BlogPost","query":{"where":{"category":"$params.slug.category"},"sort":"-publishedAt","limit":4}}}'
+```
+
+The three source types select matching Labels, one-off Singles, or Collection results. A Collection source's optional `query` uses the normal content query shape.
+
+## Params queries and source queries
+
+Both use the normal content query shape and may read an earlier bound value with `$params.<param>.<field>`, but they run at different stages and narrow different things:
+
+- A dependent param query runs while Studio resolves the header selectors. On `/shop/:category/:product`, the product query narrows which products can become the `:product` URL segment after a category is chosen.
+- A Collection source query runs after Studio has resolved and selected the route. On `/blog/:slug`, `relatedPosts` uses the selected post's `$params.slug.category` to narrow the entries shown in that route's editor; it does not create more routes.
+
+## Commands
+
+```bash
+fimo pages list
+fimo pages list --expand
+fimo pages set <id> --path /about --label About
+fimo pages set <id> --clear-params
+fimo pages set <id> --clear-sources
+fimo pages rename <id> <new-id>
+fimo pages delete <id>
+```

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

@@ -1,6 +1,6 @@
 # Outbound webhooks
 
-> **Beta:** Test each destination and inspect its delivery history before depending on it in production.
+> Test each destination and inspect its delivery history before depending on it in production.
 
 Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.
 

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

@@ -14,6 +14,12 @@ Use this skill for code that consumes the version-locked `fimo` package in the c
 
 Use the project-installed CLI for local inspection, code generation, and validation (`pnpm exec fimo`, `npm exec fimo`, `yarn fimo`, or `bunx --no-install fimo`, matching the lockfile). If that runner tries to install packages even though dependencies already exist, invoke the local `node_modules/.bin/fimo` executable instead. Load the `fimo-cli` skill for remote operational workflows such as schema pushes, label writes, entry mutations, and deploys. If the skill is not already available locally, fetch it with `npx fimo@latest skills get fimo-cli`.
 
+Fimo API values may be class-backed tracked objects, not plain JSON. Keep them
+as-is on the server. Before passing them to a `'use client'` prop or a
+plain-JSON consumer such as Markdown, RSS, or JSON-LD, use the generated
+serializer and hydrate them in the client when the generated client requires
+it. Load the framework reference for the exact boundary.
+
 ## Orient before writing
 
 1. Run the project-installed `fimo describe --json` in a linked project and read `data.framework.slug`, schemas, locales, and tree. If the project is not linked yet, inspect `package.json` and the app directory instead.
@@ -35,6 +41,10 @@ Framework routing:
 - Nuxt, Remix, Vue, or another hosting-only setup → `references/frameworks/hosting.md`. Do not invent an SDK adapter that the installed package does not export.
 - No framework (static generator, plain HTML, a build script) → `references/frameworks/hosting.md` § `runtime`: leave `runtime.framework` unset.
 
+For public-site performance or navigation work, also load the matching
+`references/best-practices/astro.md`, `references/best-practices/sveltekit.md`,
+or `references/best-practices/next.md` reference.
+
 When a project's framework version is uncertain, load
 `references/frameworks/compatibility.md`. Use the project's installed version
 and the documented adapter range; do not assume that a framework profile means
@@ -60,6 +70,7 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Media values, `<Image>`, `<StaticImage>` → `references/assets.md`
 - Static editable copy: `Label`, `t()`, providers, and server label readers → `references/labels.md`
 - Locale ownership and framework handoff → `references/locales.md`
+- Upgrading a React Router app that imports `fimo/react-router/routes` → `references/migrations/react-router-route-ownership.md`
 - Astro connector and output/adapter contract → `references/frameworks/astro.md`
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`

package/assets/skills/fimo-code/assets/react-router-locales/LocaleLayout.tsx

@@ -0,0 +1,12 @@
+import { FimoProviders } from 'fimo/react-router';
+import { Outlet, useParams } from 'react-router';
+
+export default function LocaleLayout() {
+  const { locale } = useParams();
+
+  return (
+    <FimoProviders locale={locale}>
+      <Outlet />
+    </FimoProviders>
+  );
+}

package/assets/skills/fimo-code/assets/react-router-locales/routes.ts

@@ -1,11 +1,12 @@
 import type { RouteConfig } from '@react-router/dev/routes';
-import { index, route } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
+import { layout, route } from '@react-router/dev/routes';
 
 const routes = [
-  index('./pages/Index.tsx', { id: 'home' }),
-  route('pricing', './pages/Pricing.tsx', { id: 'pricing' }),
-  route('blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?', './pages/Index.tsx', { id: 'home' }),
+    route(':locale?/pricing', './pages/Pricing.tsx', { id: 'pricing' }),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
+  ]),
 ] satisfies RouteConfig;
 
-export default fimoRoutes(routes) satisfies RouteConfig;
+export default routes;

package/assets/skills/fimo-code/references/best-practices/astro.md

@@ -0,0 +1,47 @@
+# Astro website best practices
+
+Load `references/frameworks/astro.md` first.
+
+- Put the document shell, navigation, and shared metadata in a layout.
+- Render the H1, primary copy, canonical, and crawlable links in the initial HTML.
+- Pass tracked Fimo values intact to Fimo components; use `String(value)` only for attributes and URLs. Flattening removes Studio's edit target.
+- Start independent Fimo reads with `Promise.all`; do not repeat page reads in children.
+- Ship no client JavaScript for static content. Use `client:visible` or `client:idle` below the fold; reserve `client:load` for immediately required interaction.
+- Use `server:defer` only for slow, secondary, or personalized UI, with a stable fallback. Keep primary content and metadata outside server islands.
+- Prerender when rebuild freshness is acceptable; render on demand when edits must appear immediately.
+- Give images dimensions; eagerly load only the likely LCP image.
+- Return a real 404 for a missing slug. Build one canonical from the public origin and normalized route, never the preview host.
+
+## Consider incremental static builds
+
+For Astro 7.2+ sites with many `getStaticPaths()` pages:
+
+```js
+import { defineConfig } from 'astro/config';
+import { fimo } from 'fimo/astro/config';
+
+export default defineConfig({
+  integrations: [fimo()],
+  experimental: { incrementalBuild: true },
+  build: { concurrency: 1 },
+});
+```
+
+```astro
+export async function getStaticPaths() {
+  const { items } = await Story.list({ limit: 100 });
+  return items.map((story) => ({
+    params: { slug: String(story.slug) },
+    props: { story },
+    cacheKey: story.updatedAt,
+  }));
+}
+```
+
+- The `cacheKey` must change for every rendered data dependency, including shared labels, settings, and related entries. A slug is not an invalidation key.
+- Persist `node_modules/.astro/` between builds. Use `astro build --force` after middleware changes or to ignore the cache.
+- Keep build concurrency at `1`. Pages with server islands also need a stable `ASTRO_KEY`.
+
+Verify production HTML, valid and missing slugs, canonical output, shipped scripts, API waterfalls, and image sizing. For incremental builds, prove one unchanged and one invalidated path.
+
+Sources: [incremental builds](https://docs.astro.build/en/reference/experimental-flags/incremental-build/) and [server islands](https://docs.astro.build/en/guides/server-islands/).

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -0,0 +1,42 @@
+# Next.js website best practices
+
+Load `references/frameworks/next.md` and the matching router reference first. Instant Navigations apply only to Next 16.3+ App Router projects.
+
+- Use Server Components by default and keep Client Components at interactive leaves.
+- Keep root layouts cheap; put slow page-specific Fimo reads in the page or a nested component.
+- Start independent reads together. Server Components should call generated Fimo modules directly, not application Route Handlers.
+- Keep tracked Fimo values intact in Server Components. Use generated `serialize()`/`hydrate()` at JSON prop boundaries. Generated client hooks are already hydrated; pass their values directly to Fimo components.
+- Render the H1, primary copy, canonical, and crawlable links in the server result. Do not repeat the read after hydration.
+- Give images dimensions; prioritize only the likely LCP image.
+
+## Instant Navigations
+
+```ts
+import type { NextConfig } from 'next';
+import { withFimo } from 'fimo/next/config';
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+  partialPrefetching: true,
+};
+
+export default withFimo(nextConfig);
+```
+
+Choose per blocking Fimo read:
+
+- **Stream:** use `Suspense` for fresh or slow data. Prefer this when Studio edits must appear immediately.
+- **Cache:** use `use cache` only with a publication-aware lifetime and tag invalidation.
+- **Block:** set `instant = false` as low as possible when partial UI is misleading.
+
+Keep default `<Link>` prefetching. Use `prefetch={true}` only for a few high-intent links; large lists can overload the content API. Prefetch rendering must be side-effect free.
+
+Use `instant = true` to find blocking code, then verify with `next build` and `next start`; development does not prefetch. Inspect the shell and streams with Navigation Inspector.
+
+- Call `notFound()` for a missing slug.
+- Build one canonical from `metadataBase` and the normalized route, never the preview host.
+- Avoid duplicate content reads between `generateMetadata` and the page.
+
+Verify valid and missing slugs, canonical and initial HTML, shipped JavaScript, duplicate reads, image sizing, instant shell rendering, streaming, freshness, and bounded prefetching.
+
+Sources: [Instant Navigations](https://nextjs.org/blog/next-16-3-instant-navigations), [`partialPrefetching`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/05-config/01-next-config-js/partialPrefetching.mdx), and [`instant`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/instant.mdx).

package/assets/skills/fimo-code/references/best-practices/sveltekit.md

@@ -0,0 +1,17 @@
+# SvelteKit website best practices
+
+Load `references/frameworks/sveltekit.md` first.
+
+- Keep shared navigation, labels, and metadata in layouts; keep slow page data in the narrowest `+page.server.ts` or `+layout.server.ts`.
+- Pass the request `event`. Serialize generated Fimo values at the load boundary and render them with Fimo components, which restore their Studio editing metadata. Do not flatten tracked values first.
+- Start independent reads together. Use `await parent()` only for a real parent-data dependency.
+- Await primary content. Stream only slow, non-essential promises; add a stable `{#await}` fallback, an error branch, and an early rejection handler when the promise does not use SvelteKit's `fetch`.
+- Render the H1, primary copy, canonical, and crawlable links during SSR. Do not disable SSR or repeat the read after hydration.
+- Keep browser JavaScript at interactive leaves.
+- Use request-time loads when edits must appear immediately. Prerender or cache only when rebuild or invalidation behavior is explicit.
+- Give images dimensions; eagerly load only the likely LCP image.
+- Call `error(404, ...)` for a missing slug. Build one canonical from the configured public origin and normalized route, never the preview host.
+
+Verify the production server response, valid and missing slugs, canonical output, streamed errors, shipped JavaScript, API waterfalls, and image sizing.
+
+Source: [SvelteKit load and streaming](https://svelte.dev/docs/kit/load).

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

@@ -26,6 +26,11 @@ Marks: `bold`, `italic`, `underline`, `strike`, `code`, and `link`.
 
 Use semantic nodes instead of flattening long content into paragraphs. Render the returned value with the framework's `<RichText>` primitive so source metadata survives.
 
+Richtext and other API values may carry class-backed tracking metadata. Values
+rendered by server Fimo primitives can stay intact. Serialize them before a
+plain-JSON consumer (Markdown, RSS, JSON-LD) or a client prop, then use the
+generated client hydration helper where required.
+
 ## Entry payload
 
 CLI entry writes put every value, including the collection slug, under `data`:

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

@@ -56,12 +56,15 @@ Never declare `id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `upd
 | `richtext`  | Tiptap JSONContent         | formatted content                        |
 | `number`    | number                     | quantities and ordering fields           |
 | `boolean`   | boolean                    | flags                                    |
-| `date`      | ISO date string            | dates/timestamps                         |
+| `date`      | ISO date string            | calendar days; loose about the form      |
+| `datetime`  | ISO instant with offset    | exact moments (`2026-08-13T09:30:00Z`)   |
 | `media`     | media object or array      | images, video, files                     |
 | `json`      | JSON                       | structured metadata                      |
 | `reference` | `{ "id": "..." }` or array | links to another schema                  |
 | `blocks`    | ordered object array       | nested/repeatable sections               |
 
+A `datetime` value must carry `Z` or `±HH:MM`; a bare day or a naive local time is rejected. Render it with `<DateTime>`, which keeps the whole instant in the `<time datetime>` attribute, and a `date` with `<Date>`. `unique` is not supported on `datetime`.
+
 An enum string uses `options`; its optional `default` must be one of them:
 
 ```json

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

@@ -73,7 +73,7 @@ const [settings, stories, labels] = await Promise.all([
 }
 ```
 
-The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
+The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `DateTime`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
 
 ## Forms
 
@@ -107,11 +107,13 @@ export async function getStaticPaths() {
 
 ## Locales
 
-The application resolves the locale — route prefix, middleware, domain, `Astro.currentLocale`, cookie, or its i18n library — and passes it to content reads and `getLabels({ locale })`. When a server read omits `locale`, the Fimo API resolves the project default; do not hardcode a fallback locale in application code. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
+Configure Astro i18n from `.fimo/config.json#i18n` and use `Astro.currentLocale` for content reads, `getLabels({ locale })`, and `<html lang>`. The standard starter keeps the configured default locale unprefixed and prefixes the others. Existing applications may instead resolve locale through middleware, domains, cookies, or another application-owned strategy. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
+
+The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales in `.fimo/config.json`; Astro's native i18n router validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
 
 ## Studio route catalog
 
-`.fimo/config.json#routes` is an optional catalog of pages for Studio navigation, not router configuration. Never replace or infer Astro's route files, redirects, middleware, or 404 behavior from it. Keep paths canonical and unlocalized, and describe dynamic segments with `params` so Studio can list entries:
+`.fimo/config.json#routes` is an optional catalog of pages for Studio navigation, not router configuration. Never replace or infer Astro's route files, redirects, middleware, or 404 behavior from it. Keep routes without locale ownership canonical and unlocalized. For a locale-aware route, declare the reserved `/:locale` segment and mark it optional in `params`; describe other dynamic segments with `params` so Studio can list entries:
 
 ```json
 {

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

@@ -49,9 +49,12 @@ Locally, the app derives its env from the **git branch**: `fimo/vite`,
 API URL from `.fimo/project.json`
 (`projectId` + `tenantApiBaseUrl`, recorded once at `init`/`clone`/`link`) and
 expose the Vite, Next and public (`PUBLIC_*`) aliases plus `FIMO_ENV` /
-`NEXT_PUBLIC_FIMO_ENV` at startup. No env file is written on a switch, so a plain `git checkout` is a
+`NEXT_PUBLIC_FIMO_ENV` at startup. The Vite connectors derive them during both
+dev and production builds, and `withFimo` derives them in `next dev`, `next
+build`, and `next start`, so a linked project builds and serves locally without
+exporting them by hand. No env file is written on a switch, so a plain `git checkout` is a
 complete env switch. Never hardcode a tenant URL in application source. One
-rule, per variable: a value the user set explicitly (`.env`, shell, their own
+rule, per variable: a non-empty value the user set explicitly (`.env`, shell, their own
 `define`) is left alone, and Fimo fills the variables they did not set.
 
 For a framework whose alias is not in that list yet, preserve or add its normal

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

@@ -76,6 +76,12 @@ This example demonstrates request-time rendering, not a recommended locale polic
 
 ## Client Components
 
+When a Server Component passes Fimo content into a Client Component, it MUST
+serialize with the generated server module and the Client Component MUST
+hydrate with the matching generated `.client` module. Do not pass a raw Fimo
+value merely because its enumerable fields look JSON-safe. No conversion is
+needed while the value stays inside server rendering.
+
 Client Components use the generated `.client` module and `fimo/next/client`:
 
 ```tsx

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

@@ -33,6 +33,16 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 - Pages Router i18n: reuse `context.locale` in data functions and `router.locale`/page props on the client.
 - Default-only app: omit locale arguments and let Fimo use `.fimo/config.json#i18n.defaultLocale` (fallback `en`).
 
+## 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.
+
+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.
+
+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.
+
+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.
+
 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.
 
 Before creating non-default Fimo labels or content variants, confirm that those locales are enabled for the linked Fimo project. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; `.fimo/config.json` documents the application's locale policy, but `fimo validate` does not add project locales.
@@ -54,6 +64,6 @@ Fimo owns:
 - client content/label context after receiving the locale;
 - editable source metadata.
 
-Do not add `.fimo/config.json#routes` to a Next project yet. The current route-metadata validator expects React Router's `src/routes.ts`; a first-class Next Studio catalog and preview bridge are separate product work. Do not create a fake `src/routes.ts` to satisfy that check.
+The new-project shell includes a small `.fimo/config.json#routes` catalog for Studio. It describes the page URLs but does not configure the App Router. Keep the `app` directory authoritative, and do not create a fake `src/routes.ts` or a universal Fimo route helper.
 
-Do not introduce `[locale]` segments, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.
+Do not introduce new locale middleware, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.