fimo 2.6.0-staging.4 → 2.7.0-experimental.1

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

@@ -1,6 +1,20 @@
 # Analytics workflow
 
-Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
+Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline.
+Ingestion accepts any resolved branch, so do not assume that every possible preview
+sender is excluded; a preview visit is stored under its own branch rather than dropped.
+
+For tracking setup, load `fimo-code`. Reading analytics does not install a tracker.
+If counts are zero, check the selected branch, built scripts, enabled setting,
+browser requests and stored results before diagnosing a missing implementation.
+A successful HTTP response alone does not establish that a row was stored.
+Use `fimo-code` analytics setup for the standalone `fimo-analytics` APIs.
+Confirm that the selected package release contains them before generating imports;
+older Fimo releases and existing published sites do not acquire a tracker automatically.
+
+For Studio tracking verification, load `fimo-studio` and its analytics reference.
+Its tracking status is independent of the chart range and device filter; a failed
+status check is not evidence of missing tracking.
 
 Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
 
@@ -13,7 +27,7 @@ fimo --branch prod analytics pageviews --days 7 --json
 fimo --branch prod analytics top countries --json
 ```
 
-Structured read results include `branch` (`data.branch` in the CLI JSON envelope). Check it before interpreting metrics. An intentional `--branch <name>` overrides the default; zero traffic on `main` or a preview branch does **not** mean the published site has no traffic. Preview visits are not collected. If publication or access is unavailable, report that limitation; do not fall back to another branch or present the failure as zero traffic.
+Structured read results include `branch` (`data.branch` in the CLI JSON envelope). Check it before interpreting metrics. An intentional `--branch <name>` overrides the default; zero traffic on `main` or a preview branch does **not** mean the published site has no traffic. Preview visits do not appear in published traffic. If publication or access is unavailable, report that limitation; do not fall back to another branch or present the failure as zero traffic.
 
 SDK and hosted MCP reads also default omitted `branch` to `prod` and return the selected `branch`. Annotation **writes** keep the current/explicit Branch and its existing permissions; the read default does not grant permission to write to `prod`.
 

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

@@ -90,7 +90,7 @@ Write the locale into a route's path with the reserved `:locale` segment, never
 | `/: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.
+- `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 an `entry` param that needs both, unless it declares `"type": "external"`: an external param takes no other keys, and the application owns its values.
 - `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.
@@ -102,7 +102,7 @@ Register the same shape in the router. React Router spells the omittable segment
 route(':locale?/blog/:slug', './pages/BlogPost.tsx');
 ```
 
-These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for content-backed `params` and declared `sources`.
+These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for the three `params` types 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.
 

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

@@ -7,15 +7,27 @@ Pages can mirror the application's routes in Fimo Studio. It gives editors a rou
 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.
+- `params` optionally describes each path placeholder: an entry bound to a Collection so Studio can select a concrete route in the page header, the reserved `locale` segment, or a value the application owns.
 - `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:
+Each param key matches a `:placeholder` in `path`. For an entry param, `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"}}}'
 ```
 
+A descriptor's `type` is optional and selects one of three param kinds:
+
+- `entry` (the default) binds the placeholder to a Collection with `schema`, `queryField`, `displayField`, and an optional `query`.
+- `locale` is the reserved `:locale` segment with an optional `optional` boolean. See `references/locales.md`.
+- `external` takes no other keys. The application owns the values: Fimo matches the segment from the URL and never looks it up in the CMS.
+
+```bash
+fimo pages set <id> --path '/cartes/:slug' --params '{"slug":{"type":"external"}}'
+```
+
+Declare a placeholder `external` when its values are not Fimo content — a catalogue synced from an upstream source and stored as a media asset, ids that exist only in the visitor's browser, computed archive or pagination segments, third-party ids. Never bind a placeholder to an unrelated Collection to make `fimo validate` pass. `fimo pages list` reports `dynamic:external` and `fimo pages list --expand` skips the route; `fimo/paths` and the generated sitemap emit nothing for it, so the application enumerates those URLs itself. A `$params.<name>.<field>` expression in a param query or a source may reference entry params only. A route may mix kinds: entry params keep their selectors in Studio, and an external param takes a typed value in the preview header.
+
 `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

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

@@ -76,6 +76,14 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 
+## Analytics
+
+For pageview installation, read [references/analytics.md](references/analytics.md).
+`FimoProviders` from `fimo-react-router` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are configured. Inspect the installed version and
+browser requests before adding a sender. Hosting or the neutral Vite plugin alone
+does not install a tracker. Older releases do not acquire new package exports.
+
 ## Non-negotiable boundaries
 
 - Do not hardcode editor-owned collections, page content, labels, or media in JSX.

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

@@ -0,0 +1,104 @@
+# Pageview tracking
+
+First inspect the installed package and the built page. React Router's
+`FimoProviders` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are present. Do not mount another sender beside an
+unmodified legacy tracker. The neutral Vite plugin and hosting alone do not
+install tracking.
+
+## Standalone setup
+
+Install a released version of `fimo-analytics` that exposes the adapter you need.
+Keep any version/channel selector the user already chose. An older `fimo`
+release does not imply these standalone APIs exist, and existing published
+sites need a code update to gain missing instrumentation.
+
+```sh
+pnpm add fimo-analytics
+```
+
+Obtain the tenant API base URL from the project's configured Fimo connection,
+and append `/e/p`. Pass that complete URL as `endpoint`. Never infer it from the
+site's public URL, guess a project hostname, or invent a discovery command. If
+the connection does not supply a tenant endpoint, obtain it before enabling
+tracking. A configured origin-relative proxy is also accepted.
+
+| Framework      | Import                                              | Placement                                    |
+| -------------- | --------------------------------------------------- | -------------------------------------------- |
+| React          | `{ Analytics }` from `fimo-analytics/react`         | Application root                             |
+| React Router   | `{ Analytics }` from `fimo-analytics/react-router`  | Inside root router                           |
+| Next App/Pages | `{ Analytics }` from `fimo-analytics/next`          | Root layout or `_app`                        |
+| Astro          | default `Analytics` from `fimo-analytics/astro`     | Shared layout, no `client:*`                 |
+| Svelte         | default `Analytics` from `fimo-analytics/svelte`    | Root component                               |
+| SvelteKit      | default `Analytics` from `fimo-analytics/sveltekit` | Root `+layout.svelte`                        |
+| Vue            | `{ Analytics }` from `fimo-analytics/vue`           | Root component, history routing              |
+| Nuxt           | `modules: ['fimo-analytics/nuxt']`                  | `analytics: { endpoint, enabled }` in config |
+
+Components accept `endpoint` and `enabled`. React example:
+
+```tsx
+import { Analytics } from 'fimo-analytics/next';
+<Analytics endpoint={endpoint} enabled={isProduction} />;
+```
+
+For Nuxt, also install the optional build peer with `pnpm add -D @nuxt/kit`.
+Next owns its client and Suspense boundaries. SvelteKit uses committed
+navigation; Nuxt covers reused pages and query changes. Generic React, Vue and
+Svelte observe history. For a router that changes the URL before committing,
+use the manual core. For Vue Router, initialize in `onMounted` after initial
+router readiness, send once, subscribe to `router.afterEach`, send only when
+`failure` is falsy, and remove the subscription and destroy on unmount.
+
+```ts
+import { init } from 'fimo-analytics';
+const analytics = init({ endpoint, enabled: isProduction, routing: 'manual' });
+// In the router's successful-navigation callback:
+analytics.pageview();
+// During cleanup:
+analytics.destroy();
+```
+
+Vanilla apps can omit `routing` to track the initial page and browser history.
+Hash routers can pass `{ path: resolvedVirtualPath, pageName }` to `pageview`;
+the React Router adapter already reads its router's virtual location.
+
+For plain HTML, copy the installed `dist/browser.js` into static assets:
+
+```html
+<script defer src="/fimo-analytics.js" data-endpoint="https://YOUR-TENANT-API-HOST/e/p" data-enabled="true"></script>
+```
+
+Use a classic script, not `type="module"`. Set `data-enabled="false"` in preview
+builds. No framework peer is required for core or HTML. Framework peers are
+optional and only the chosen adapter's framework is needed.
+
+## Choose the enabled guard
+
+Tracking defaults to enabled, so always pass `enabled`. Never use `NODE_ENV`:
+a Fimo hosted preview is a production build, so that guard leaves previews
+reporting. Read the build variable Fimo already sets:
+
+| Framework                 | Guard                                              |
+| ------------------------- | -------------------------------------------------- |
+| React Router and any Vite | `import.meta.env.VITE_ENABLE_ANALYTICS === 'true'` |
+| Next.js                   | `process.env.NEXT_PUBLIC_FIMO_ENV === 'prod'`      |
+| Build-time server env     | `process.env.FIMO_ENV === 'prod'`                  |
+
+Astro, SvelteKit, Svelte and Vue have no browser-visible environment name from
+Fimo. Read `FIMO_ENV` at build time and pass the boolean into the bundle through
+the framework's own public-variable mechanism. Do not invent a `PUBLIC_FIMO_ENV`
+and do not expose the whole environment name when a boolean is enough.
+
+## Verify the installed integration
+
+Standalone tracking defaults to enabled. Supply an explicit production guard;
+`bl_preview_token` also suppresses sends. SSR and disabled calls are inert.
+Do not add browser secrets, project IDs or branch claims to payloads.
+
+Verify one initial POST, navigation, query-only changes, back/forward and a
+route revisit. Check duplicate mounts and cleanup. Existing visitor/session
+storage keys are retained; blocked storage uses per-document IDs. Delivery is
+best effort and has no retries. A 202 response alone does not prove persistence;
+check recorded analytics separately. Framework peer ranges are not proof that
+every older framework release was tested. Use the installed package's version
+qualification and preserve existing supported integrations when upgrading.

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

@@ -170,6 +170,8 @@ The new-project shell pairs unprefixed default-locale pages with a parallel `[lo
 }
 ```
 
+A dynamic segment whose values are not Fimo content takes `{ "type": "external" }` instead of a Collection binding; Fimo matches it from the URL, and the page's own `getStaticPaths` (or on-demand rendering) supplies those values.
+
 ## Client islands
 
 Generated content reads remain server-only. Preserve existing islands and do not add React or a client SDK to work around this boundary.

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

@@ -33,6 +33,7 @@ Read the relevant reference file when the user's question matches a topic.
 | ------------------------ | --------------------------------------- | ----------------------------------------------------- |
 | Command Palette          | references/command-palette.md           | "What can I open with Cmd+K?", "Quick actions"        |
 | Publish & Deploy         | references/publish-and-deploy.md        | "How do I publish?", "How do I make my site live?"    |
+| Analytics                | references/analytics.md                 | "Is tracking working?", "Why are analytics empty?"    |
 | Custom Domains           | references/custom-domains.md            | "How do I use my own domain?", "DNS setup"            |
 | Content Management (CMS) | references/cms.md                       | "How does the CMS work?", "How do I add blog posts?"  |
 | Media Library            | references/media-library.md             | "How do I upload images?", "Where are my files?"      |

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

@@ -0,0 +1,28 @@
+# Analytics
+
+Open **Analytics** in the project's workspace navigation. It may be inside
+**More** at narrower desktop widths. This workspace reports the published site,
+regardless of the editing branch currently selected.
+
+Publishing alone does not confirm pageview tracking. Before publication, the
+page offers setup guidance without an **Open site** link.
+
+For a published site:
+
+- **Waiting for the first pageview** means no pageviews are stored for it.
+  **Open site** lets the user visit the published address. **Set up tracking**
+  opens the installation guide. A visit must run a configured tracker to count.
+- **Pageviews received** shows the last pageview timestamp across available
+  history. Changing the chart's date range or device filter does not reset it.
+  Earlier traffic proves tracking worked then, not that a later deployment
+  still sends events.
+- **Tracking status unavailable** means the status could not be checked.
+  **Check again** retries it. Do not interpret this as an uninstalled tracker.
+  Charts that loaded successfully remain visible.
+
+Studio checks every 15 seconds while waiting in a visible tab. The first
+pageview refreshes the charts automatically. Processing may take longer than
+one check. Do not diagnose a missing tracker from zero chart counts alone.
+
+Users need analytics viewing permission. Date ranges and grouping apply to the
+charts; available history depends on the organization's analytics access.

package/dist/cli/bundle.json

@@ -1,8 +1,8 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-14T08:59:44.223Z",
-  "cliVersion": "2.5.1",
+  "bundledAt": "2026-09-29T12:38:55.114Z",
+  "cliVersion": "2.6.0",
   "external": [
     "oxc-parser",
     "fsevents",