fimo 0.9.0-experimental.7 → 0.9.0-experimental.9

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

@@ -50,9 +50,148 @@ unbound pages in the generated prompt. Your job:
    `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 —
+   Never repeat the folder/category in the label: the `/features/agents` page
+   is labeled "Agents", NOT "Feature: Agents" — the Studio tree already nests
+   it under Features.
+   Labels must read like a human wrote them: acronyms uppercase ("Agentic
+   CMS", "AI Stack", "SEO GEO" — never "Agentic Cms"), no two sibling pages
+   with the same name (a bound template is named after its schema — "Blog
+   Post" next to the "Blog" index; the machine does this when it binds, fix
+   any leftover with `--label`).
+   When the site's NAV groups flat pages editorially (a "Resources" menu over
+   /for-developers, /for-founders…), mirror it with
+   `npx fimo pages set <id> --group "Resources"` — the Studio Pages tree
+   folds them under that group even without a shared URL segment.
+4. Map each page to its label keys when they diverge. The Studio shows a
+   page's labels by key prefix, defaulting to `<pageId>.` — but wrapped keys
+   derive from FILE names (`AiCms.tsx` → `ai-cms.*`) or data files
+   (`personas.*`), which can differ from the URL-derived page id
+   (`agentic-cms`). A page whose Studio view is EMPTY almost always means
+   this mismatch. `fimo migrate` PREFILLS `labelPrefixes` wherever it can
+   prove the join (a staged key appears verbatim in the route's component
+   file) and the prompt § Routes & pages lists every UNCLAIMED prefix left.
+   Your job: place each unclaimed prefix — claim it with
+   `npx fimo pages set <id> --label-prefix "<prefix>"` (comma-separated for
+   several; claims MERGE into the existing list so machine-prefilled
+   prefixes survive, `""` clears the whole list) when one page renders those keys, or leave it
+   deliberately when it is shared (chrome, multi-page data files) and say so
+   in your report. No prefix may end up merely forgotten.
+5. Give each page the Lucide icon that best matches its CONTENT:
+   `npx fimo pages set <id> --icon <kebab-name>` (pricing → `tag`, blog →
+   `newspaper`, contact → `mail`, legal pages → `scale`, team/about →
+   `users`, docs → `book-open`). Read the page component to judge. Use
+   well-known Lucide names only — an unknown name silently falls back to
+   the default file icon in the Studio. Skip the flag when nothing clearly
+   fits.
+6. Verify: `npx fimo pages list --expand` materializes every instance —
    each page the site's nav links to must appear as a real URL.
 
+## Shared chrome → Single Types (the content-model rule)
+
+A site's content model must read like a CMS, not like an implementation:
+
+- **Chrome** (header, footer, nav, menus, banners) is edited as ONE thing →
+  a SINGLE TYPE per piece (`src/schemas/<Name>.json` with
+  `"isSingleton": true`, real fields mirroring the source: nav items as an
+  array/blocks field, logo as media), pushed with `npx fimo schemas push`,
+  its ONE document written from the source values with
+  `npx fimo documents set <Name> --body '<json>'` (singletons REJECT the
+  entries endpoints), component rewired to read it. Never a loose label
+  pile, never a collection.
+- **Page-scoped structure** (a pricing page's FAQ list) → a component array
+  on that page's Single, or a collection + reference when genuinely reused
+  across pages. Never an orphan collection nobody can situate. CLAIM the
+  single on its page (`npx fimo pages set pricing --single Pricing`) — it
+  then edits inline in the page's Studio view and leaves the Singles tab.
+- **Real repeating content** (blog posts, team members) → a collection, with
+  HUMAN slugs derived from the display field (never `faq-item-<hash>`), and
+  schema field order matching reading order (question before answer).
+- **A page's SECTIONS are its Single's nested blocks.** A marketing page is
+  a sequence of sections (hero, logo strip, features grid with grouped
+  cards, testimonials, integrations, stats, FAQ) — model the page as ONE
+  Single whose fields are nested block components mirroring that structure
+  (blocks nest: a `features` field holds groups, each group holds cards).
+  Section card lists are NEVER "page furniture" exemptions when they carry
+  real copy — an exemption hides marketing content from the editor, which
+  is a failed migration for that section. Claim the Single on its page.
+  **The machine BUILDS this model for you**: `fimo migrate` writes, per
+  multi-section page, an analysis draft (`.fimo/migration/page-drafts/`,
+  regenerate with `npx fimo pages draft`) AND a ready page Single
+  (`.fimo/migration/page-singles/<Uid>.json` — singleton schema + document
+  filled with the staged label values and the source block rows). Sections
+  flagged `"shared": true` render on several pages — that is chrome: model
+  each once as a Single Type, never as a per-page block. The `wrap --check`
+  Content-model gate fails while a built Single is neither claimed
+  (`pages set <id> --single <Uid>`) nor recorded under
+  `wrap.modelDeviations` (`{"page": "<id>", "reason": "…"}`) — a reason the
+  user would accept; "faster as labels" is not one. Your work per page:
+  rename machine field keys to editorial names, push, `documents set`,
+  rewire the reads with source fallback, claim.
+
+  **Worked real example** (the Fimo homepage, the model the user ratified):
+  the page renders hero → logo strip → features grid (3 groups, each with
+  cards) → testimonials → integrations → stats bar → FAQ. Its Single:
+
+  ```json
+  {
+    "uid": "Home",
+    "isSingleton": true,
+    "fields": {
+      "builtOnTheBest": {
+        "type": "blocks",
+        "schema": { "fields": { "name": { "type": "string" }, "domain": { "type": "string" } } }
+      },
+      "features": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "subtitle": { "type": "string" },
+            "cards": {
+              "type": "blocks",
+              "schema": { "fields": { "title": { "type": "string" }, "description": { "type": "text" } } }
+            }
+          }
+        }
+      },
+      "testimonials": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "quote": { "type": "text" },
+            "metricValue": { "type": "string" },
+            "metricLabel": { "type": "string" },
+            "author": { "type": "string" },
+            "role": { "type": "string" }
+          }
+        }
+      },
+      "ecosystem": {
+        "type": "blocks",
+        "max": 1,
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "stats": { "type": "blocks", "schema": { "fields": { "label": { "type": "string" } } } }
+          }
+        }
+      },
+      "faqs": { "type": "blocks", "schema": { "fields": { "q": { "type": "string" }, "a": { "type": "text" } } } }
+    }
+  }
+  ```
+
+  Note what made it right: block names are the on-page section titles
+  ("Built on top of the best" → `builtOnTheBest`), field names are ROLES
+  (`title`, `quote`, `author`) never copy slugs, a logo strip carries its
+  ITEMS (not just its heading), computed live values (stat numbers) stay in
+  code, and the whole thing was claimed on the page. Smart deviations were
+  reported, not silent.
+
+- **Plumbing** (`WrappedRichText`, `WrappedMedia`) is storage — the Studio
+  hides it from Collections and shows the entries under their pages; never
+  present it as content in your report.
+
 ## SEO — a USER decision, never wired by default
 
 Who owns SEO metadata is recorded in `.fimo/migration/manifest.json` →

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-25T21:00:19.368Z",
+  "bundledAt": "2026-07-29T10:21:20.778Z",
   "cliVersion": "0.8.0",
   "external": [
     "oxc-parser",