fimo 0.9.0-experimental.5 → 0.9.0-experimental.7

package/assets/agent-templates/content-translator/scripts/write-locale-files.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool: write-locale-files
+ *
+ * For locale-keyed JSON files in `src/locales/<locale>.json`, fill in
+ * missing keys from the default-locale file using the configured
+ * translation provider. Run after translate-entries when projects mix
+ * CMS-driven copy with hardcoded i18n strings.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+interface Catalog {
+  [key: string]: string;
+}
+
+async function readCatalog(file: string): Promise<Catalog> {
+  try {
+    const text = await fs.readFile(file, 'utf8');
+    return JSON.parse(text) as Catalog;
+  } catch {
+    return {};
+  }
+}
+
+async function writeCatalog(file: string, catalog: Catalog): Promise<void> {
+  await fs.writeFile(file, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
+}
+
+async function translate(text: string, _to: string): Promise<string> {
+  // Stub — provider-specific call.
+  return text;
+}
+
+async function main(): Promise<void> {
+  const defaultLocale = process.env.FIMO_DEFAULT_LOCALE ?? 'en';
+  const targetLocales = (process.env.FIMO_TARGET_LOCALES ?? '').split(',').filter(Boolean);
+  const localesDir = process.env.FIMO_LOCALES_DIR ?? 'src/locales';
+
+  const defaultFile = path.join(localesDir, `${defaultLocale}.json`);
+  const defaultCatalog = await readCatalog(defaultFile);
+
+  for (const target of targetLocales) {
+    const targetFile = path.join(localesDir, `${target}.json`);
+    const targetCatalog = await readCatalog(targetFile);
+    let dirty = false;
+
+    for (const [key, sourceValue] of Object.entries(defaultCatalog)) {
+      if (targetCatalog[key]) {
+        continue;
+      }
+      targetCatalog[key] = await translate(sourceValue, target);
+      dirty = true;
+    }
+
+    if (dirty) {
+      await writeCatalog(targetFile, targetCatalog);
+      console.log(`Wrote ${targetFile}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/assets/agents-starter/claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(fimo:*)",
+      "Bash(npx fimo:*)",
+      "Bash(pnpm:*)",
+      "Bash(pnpm dlx:*)",
+      "Bash(npx:*)",
+      "Bash(git status)",
+      "Bash(git status:*)",
+      "Bash(git diff)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git restore:*)",
+      "Bash(mkdir:*)"
+    ]
+  }
+}

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

@@ -8,6 +8,7 @@
  *          }
  */
 %>
+// @ts-nocheck — generated internals are exempt from the app's own tsconfig strictness; exported types still work
 // AUTO-GENERATED ⚠️ – do not edit by hand
 import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "fimo/ui";
 <%

package/assets/skills/fimo/references/translations.md

@@ -0,0 +1,75 @@
+# Translations — package surface
+
+> For the CLI workflow (`fimo validate`, when to run validation, what sync does), see **`fimo-cli/references/translations.md`**.
+
+This file covers the **package surface**: the `t()` helper, the `useTranslations()` hook, and the code-side rules for wrapping strings.
+
+## The rule
+
+Every piece of **user-facing static text** in the app (page titles, button labels, nav items, form placeholders, empty-state copy, alt text, meta tags) MUST be wrapped in `t('key', 'Default text')`.
+
+Raw string literals in JSX are a bug — they won't show up in the Fimo admin as editable content and won't be translatable. **Hard-coded JSX text (`<h1>Welcome</h1>`) skips the entire i18n + inline-editing pipeline and becomes invisible to the editor.**
+
+## Setup (already wired)
+
+Translations are wired automatically by the `fimo/vite` build plugin. It exposes a `virtual:translations` module sourced from `<projectRoot>/translations/en.json`, and `useTranslations()` reads from that virtual module — there's no provider to add or remove. The app entry is `src/root.tsx`, which wraps the app in `<FimoProviders>` from `fimo/react-router`; you never import `translations/en.json` in app code. Pages and components only call `useTranslations()`.
+
+## Usage
+
+```tsx
+import { useTranslations, Text } from 'fimo/ui';
+
+export function Hero() {
+  const { t } = useTranslations();
+  return (
+    <section>
+      <h1>
+        <Text value={t('hero.title', 'Welcome to Acme')} />
+      </h1>
+      <p>
+        <Text value={t('hero.subtitle', 'The fastest way to ship your idea.')} />
+      </p>
+      <input placeholder={String(t('hero.emailPlaceholder', 'you@example.com'))} />
+      <img alt={String(t('hero.imageAlt', 'Team collaborating'))} src="..." />
+    </section>
+  );
+}
+```
+
+- `t(key, default)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
+- For HTML attributes (`placeholder`, `alt`, `title`, `aria-label`) cast with `String(t(...))` — the attribute can't accept a `FimoString` object directly.
+
+## Hard rules (enforced by the pre-build linter)
+
+**The first argument to `t()` MUST be a string literal.** Dynamic keys break source tracking and fail the lint step.
+
+```tsx
+// ❌ BAD — variable key
+t(item.key, item.label);
+
+// ❌ BAD — template with expression
+t(`nav.${page}`, 'Page');
+
+// ✅ GOOD — put the t() call where the literal lives
+const items = [{ label: t('nav.home', 'Home') }, { label: t('nav.about', 'About') }];
+items.map((item) => <li>{item.label}</li>);
+```
+
+## Key naming
+
+- Dot-namespaced, lowercase, kebab or camelCase leaves: `hero.title`, `nav.signIn`, `footer.copyright`, `errors.required`.
+- Namespace by **page/section/component**, not by feature (`contact.form.submitLabel`, not `forms.contactSubmit`).
+- The default (second arg) is the English copy — make it final, not a TODO; it ships to production if no translation exists for the active locale.
+
+## What NOT to translate
+
+- Dynamic content from entries or forms — that's already stored in the DB (content via schemas, submissions via forms).
+- Content-type field values rendered via `fimo/ui` primitives (`<Text>`, `<RichText>`, …) — those carry their own admin-editing metadata.
+- Purely decorative / non-text (icons, logos).
+- Developer-only strings (`console.log`, error messages thrown for debugging).
+
+## Rule of thumb
+
+If a human reader sees the text AND the project owner might want to reword it in the admin, it goes through `t()`. When in doubt: wrap it.
+
+After adding or changing `t()` calls, run `fimo validate` (or rely on `fimo deploy` doing it). See `fimo-cli/references/translations.md`.

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

@@ -0,0 +1,90 @@
+# `fimo create`
+
+Scaffold a new Fimo project linked to a remote on the Fimo platform.
+
+## Command
+
+```bash
+fimo create [dir] [options]
+```
+
+| Flag                         | Required       | Purpose                                                                                                                              |
+| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `[dir]` positional           | yes in non-TTY | Target directory (e.g. `my-site`)                                                                                                    |
+| `--org <id>`                 | yes in non-TTY | Target organization **id** (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY. |
+| `--install` / `--no-install` | yes in non-TTY | Run `pnpm install` after scaffolding (or skip it).                                                                                   |
+| `--agents <list>`            | yes in non-TTY | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to write only universal AGENTS.md.                                |
+| `-a, --agent <id>`           | alternative    | Repeatable form: `-a claude-code -a cursor`.                                                                                         |
+| `--template-root <path>`     | no             | Override the bundled template (development only).                                                                                    |
+
+Without the required flags in a non-TTY shell, the command exits with `Cannot prompt in a non-interactive shell.`
+
+For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
+
+## What gets written
+
+`fimo create` scaffolds:
+
+- The project template (Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + react-router)
+- `.fimo.settings.json` — links this directory to the remote project (read-only after creation)
+- `.env` — initial env vars (currently just `VITE_API_URL`)
+- `AGENTS.md` — project rules read by all agentskills.io-compatible AI tools (Codex, OpenCode, Aider, etc.)
+- Per-agent variants based on `--agents`:
+  - `claude-code` → `CLAUDE.md` + `.claude/settings.json`
+  - `cursor` → `.cursor/rules/fimo.mdc`
+  - `windsurf` → `.windsurfrules`
+  - `gemini-cli` → `GEMINI.md`
+  - codex / opencode / aider / others → no extra file; AGENTS.md is read natively
+- The project-scope `fimo` skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) copied into each selected agent's skill dir (`.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc.). Version-locked to the bundled `fimo` package — the installed `SKILL.md` is stamped with `fimoVersion`. Refresh later with `fimo skills sync`. See `references/agent-setup.md`.
+- A git repository with `fimo` as the remote, an initial commit, and an initial push
+
+Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md without a per-agent variant.
+
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars set` and synced into a managed `.env.local` block; hidden values use `fimo secrets set`. See `references/project-vars-and-secrets.md`.
+
+## Right after scaffolding
+
+Set a human-readable display name with `fimo rename "<Name>"`. Infer it from what the user is building (e.g. "Acme Coffee" for a café site, "Jane Doe Portfolio" for a personal site). The default post-`fimo create` name is an auto-generated slug; renaming updates the dashboard label and the SEO `siteName`.
+
+```bash
+cd my-site
+fimo rename "Acme Coffee"
+```
+
+**Then kick off a warm-up deploy in the background** so the sandbox provisions and installs the user's deps (which may differ from the template's baked ones) while you generate code. The first deploy of a project's life pays a ~15-30s provisioning cost; doing it in the background means the user's first interactive deploy lands on a warm sandbox and finishes in ~4-10s instead. See `references/deploy.md` § Warm the sandbox early in a session.
+
+```bash
+fimo deploy -m "chore: init" &
+```
+
+`-m` is the commit message for any files `validate` may codegen — use a sensible conventional-commit string (e.g. `chore: init`, `chore: scaffold`).
+
+## Load the project context
+
+After `fimo create` completes, the project root has:
+
+- `AGENTS.md` (universal) plus the per-agent variant for the AI tool you're running in (e.g. `CLAUDE.md` for Claude Code, `.cursor/rules/fimo.mdc` for Cursor)
+- `.claude/skills/fimo/SKILL.md` (or the equivalent per-agent path) — the project-scope `fimo` skill, version-locked to the installed `fimo` package
+
+**These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
+
+1. `cd <project-dir>` — switch into the new project.
+2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
+3. `Read` the project skill: `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` for Cursor, etc.).
+4. From the project skill's "load these references up front" section, batch-read `references/content.md`, `references/forms.md`, `references/assets.md`, `references/labels.md`, `references/locales.md`, `references/ui.md` before generating any significant code.
+
+Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
+
+## Adding another AI tool to an existing project later
+
+If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
+
+```bash
+fimo skills install --agents=cursor       # one command — global skill + project skill + rule file
+```
+
+Run from inside the project. The command detects the project context and wires up everything for the new agent in a single shot. See `references/agent-setup.md`.
+
+## Multi-org accounts
+
+If you belong to a single organization, `fimo create` defaults to it. If you belong to multiple and don't pass `--org`, the CLI shows an interactive picker. For `fimo create`, pass the org **id** (from the `ID` column of `fimo orgs list`) — not the slug. Use `fimo orgs switch --org <id-or-slug>` to set a default for future `fimo create` invocations. See `references/account.md`.

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

@@ -0,0 +1,43 @@
+# Translations workflow
+
+> For the `t()` helper signature, `useTranslations()` hook, key naming rules, and the "wrap every user-facing string" rule — these are package surface and code conventions. See **`fimo/references/translations.md`**.
+
+This file covers the **CLI workflow** for translations.
+
+## What sync does
+
+The pre-build step scans `src/**/*.{ts,tsx,js,jsx}` for `t('literal-key', 'literal-default')` calls (skipping `src/ui` and `node_modules`), writes them to `translations/en.json`, and syncs them to the tenant DB. This makes strings editable inline by non-technical users in the Fimo admin and translatable to other locales.
+
+Code is the source of truth for English defaults.
+
+## CLI commands
+
+```bash
+fimo validate                        # run all checks + sync local state to DB (includes translations)
+fimo translations list               # inspect what's currently in the DB (read-only)
+fimo translations list --locale en   # filter by locale
+```
+
+`fimo validate` is the single entrypoint that extracts `t()` calls, rewrites `translations/en.json`, and pushes the diff to the DB. It's idempotent — run it as often as you like. It also runs automatically inside `fimo deploy`: `fimo validate` runs first (lint + codegen + DB sync), then any `translations/en.json` changes are committed and pushed alongside the rest of your code.
+
+Advanced/internal primitives (hidden from `fimo --help`, used for debugging or by the backend sandbox):
+
+```bash
+fimo scripts extract-translations    # rewrite translations/en.json locally — no DB push
+fimo scripts inject-translations     # rewrite t() defaults in src/ to match translations/en.json
+```
+
+Prefer `fimo validate` — these primitives are for narrow use cases.
+
+## When to run validate
+
+- After adding or changing any `t()` calls in code → run `fimo validate` (or rely on `fimo deploy` doing it for you).
+- After renaming/removing `t()` keys → the sync phase removes stale entries from the DB.
+
+## Workflow
+
+1. Write JSX with `t('key', 'Default')` calls. Load `fimo/references/translations.md` for the rules (literal keys, naming, what NOT to translate).
+2. Run `fimo validate` to push new keys to the DB.
+3. Editors can now change copy in the Fimo admin without code changes.
+
+For the helper signatures, hooks, and code patterns, **always** load `fimo/references/translations.md` before writing code that uses `t()`.

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

@@ -117,6 +117,8 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 - `references/wrap.md` - wrap mode: adopt a working JS codebase and wrap its
   content in place (default for source-backed JS sites).
 - `references/manifest.md` - canonical migration ledger schema.
+- `references/pages.md` - the page registry (templates, schema bindings,
+  instances), Studio preview navigation, and the opt-in per-page SEO recipes.
 - `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.
 - `references/forms.md` - form classification and Fimo replacement rules.

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

@@ -66,11 +66,22 @@ rebuild migrations:
       "wrappedMedia": 3,
       "wrappedRichText": 1
     },
+    "seo": { "decision": "external", "decidedBy": "default" },
     "planPath": ".fimo/migration/plan.json"
   }
 }
 ```
 
+`wrap.seo` records who owns the site's SEO metadata — a USER decision, like
+`wrap.dataSources`: `decision` is `"fimo"` (Fimo manages per-page SEO,
+editable in the Studio) or `"external"` (the code / an external SEO tool
+keeps ownership — the DEFAULT, nothing is ever wired on it). `decidedBy` is
+`"default"` until the user actually answered; relay defaulted records and
+rewrite them with `decidedBy: "user"`. Page bindings themselves live in the
+page registry (`fimo-config.json#routes` →
+`params: { "<param>": { "schema", "queryField", "displayField" } }`), not in
+the manifest — see `references/pages.md`.
+
 `coverage` mirrors the final `fimo migrate wrap --check` output: `wrappable`
 must be 0 (or fully accounted for by `ignored` + `unresolvedItems`, each with a
 ledger entry). `seeded` counts must match what `fimo labels list` /

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

@@ -0,0 +1,95 @@
+# Pages — the page registry, Preview navigation, and opt-in SEO
+
+A **Page** is a navigable URL surface of the site, in two forms:
+
+- **Page template** — what the app's routing declares: `/pricing` (static),
+  `/blog/:slug` (dynamic). The app's CODE is the source of truth for page
+  structure; `fimo migrate` discovers templates per framework and reconciles
+  them into the registry, `fimo-config.json#routes` (manual entries are
+  preserved). Param syntax is ALWAYS `:param` / catch-all `:param*` — never
+  `[param]`.
+- **Page instance** — a concrete page: template × content entry
+  (`/blog/:slug` × `hello-world`). Instances are NEVER stored; they derive
+  from entries through the template's binding, so they cannot drift.
+
+The registry entry shape:
+
+```json
+"blog-post": {
+  "label": "Blog post",
+  "path": "/blog/:slug",
+  "params": { "slug": { "schema": "BlogPost", "queryField": "slug", "displayField": "title" } },
+  "seo": { "title": "{{blog-post.title}} — {{siteName}}" }
+}
+```
+
+- `params[<param>]` is the **binding**: the schema whose entries materialize
+  the instances. `queryField` = the entry field substituted into the URL
+  (entry `slug` metadata always qualifies); `displayField` = the label the
+  Studio's page picker shows.
+- The Studio preview navigates ONLY what the registry describes: static pages
+  as-is, dynamic pages once bound. An unbound dynamic page navigates to a
+  literal `/blog/:slug` URL — broken by definition.
+- Locale params (`:locale`, `:lang`) are never schema-bound; tooling
+  substitutes the project's default locale. (Studio locale switching for
+  dynamic pages is a platform follow-up, not your problem.)
+
+## Completing the bindings (agent workflow)
+
+`fimo migrate` writes strong-evidence bindings itself (a rewired parent list
+page; a wired CMS with a single page-builder type) and lists candidates +
+unbound pages in the generated prompt. Your job:
+
+1. `npx fimo pages list` — see every template and its status
+   (`static | dynamic:bound | dynamic:unbound`).
+2. For each candidate/unbound page, find the schema whose entries the page
+   renders (read the page component's fetch). Apply with
+   `npx fimo pages set <id> --params '{"<param>":{"schema":"<Type>","queryField":"slug","displayField":"<field>"}}'`
+   — it validates the schema and both fields against the server. Never
+   hand-edit the JSON. If drafts are not adopted yet, run
+   `schemas adopt-drafts` FIRST and bind with the FINAL names.
+3. Add pages the scanner missed (SPA relative/wildcard routes):
+   `npx fimo pages set <id> --path /the/path --label "Label"`.
+4. Verify: `npx fimo pages list --expand` materializes every instance —
+   each page the site's nav links to must appear as a real URL.
+
+## SEO — a USER decision, never wired by default
+
+Who owns SEO metadata is recorded in `.fimo/migration/manifest.json` →
+`wrap.seo` (`{ "decision": "fimo" | "external", "decidedBy": "user" | "default" }`).
+The default is ALWAYS `external` (nothing touched — the site's code or an
+external SEO tool keeps ownership). When the prompt shows the decision as
+DEFAULTED, relay it to the user once; only an explicit user "fimo" unlocks
+wiring. Never migrate, edit, or inject metadata on the default.
+
+When the user opted into Fimo-managed SEO, the engine is the neutral
+`fimo/seo` export — pure resolution over the registry, no framework coupling:
+
+```ts
+import { getFimoSeoForPath } from 'fimo/seo';
+const seo = getFimoSeoForPath(pathname, { routeData: { 'blog-post': entry } });
+// seo.title / seo.description / seo.image / seo.robots …
+```
+
+Per-framework injection (map the resolved values to the framework's head API):
+
+- **Next (app router)** — in the layout or page, `generateMetadata()` calls
+  `getFimoSeoForPath` with the resolved pathname (+ the entry as `routeData`
+  on dynamic pages) and returns `{ title, description, openGraph: {...} }`.
+- **React Router** — already shipped: `loadFimoMetaData` / `buildFimoMeta` /
+  `fimoHtmlProps` from `fimo/react-router`.
+- **Astro** — a head partial calling `getFimoSeoForPath(Astro.url.pathname)`
+  server-side and rendering the `<meta>` tags.
+- **Nuxt** — `useSeoMeta()` fed from a server util wrapping `getFimoSeoForPath`.
+- **SvelteKit** — resolve in `+layout.server` load, render in the root
+  layout's `<svelte:head>`.
+
+Route-level `seo` blocks support `{{variables}}` resolved against
+`routeData` — per-INSTANCE metadata from one template.
+
+## Sitemap / robots
+
+Once bindings exist, `getFimoPaths` (from `fimo/paths`) materializes the full
+instance list for prerender/sitemap use. It reads the API base URL from
+`VITE_API_URL` (a plain env var or `.env` line works outside Vite). The
+`fimo pages list --expand` output is the same list, CLI-side.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-24T17:59:36.047Z",
+  "bundledAt": "2026-07-25T21:00:19.368Z",
   "cliVersion": "0.8.0",
   "external": [
     "oxc-parser",