fimo 0.9.0-experimental.10 → 0.9.0-experimental.11

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

@@ -86,9 +86,56 @@ unbound pages in the generated prompt. Your job:
 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)
+## Content model — Collection vs Single vs Component (the decision rule)
 
-A site's content model must read like a CMS, not like an implementation:
+A site's content model must read like a CMS, not like an implementation. The
+test that decides **Single Type vs Component**: EDIT IT ONCE — should it change
+on EVERY page (Single Type) or only on THIS page (Component)? That is a
+question about CONTENT, not about how many pages the STRUCTURE appears on — a
+component can appear on many pages too.
+
+| Shape                  | Repeats as entries? | Structure across pages | **Content across pages** | Edit propagates? | Examples                                                          |
+| ---------------------- | ------------------- | ---------------------- | ------------------------ | ---------------- | ----------------------------------------------------------------- |
+| **Collection Type**    | Yes (many)          | —                      | —                        | —                | Blog Post, FAQ Item, Team Member, Service                         |
+| **Single Type**        | No (one instance)   | reused                 | **SAME everywhere**      | Yes — everywhere | Header, Footer, Cookie Banner, Nav, a shared CTA _(if identical)_ |
+| **Component (Blocks)** | No                  | reused (1+ pages)      | **DIFFERENT per page**   | No — local       | a hero, a features grid, a Pricing page's plan tiers              |
+
+- **Structure appearing on many pages does NOT make it a Single.** A hero is on
+  every page but each page's hero content differs → Component. A header is a
+  Single Type because its content is identical everywhere.
+- **Single Type detection is structural:** a shared component whose content is
+  BAKED INTO the component — no per-page content props, e.g. rendered by the
+  LAYOUT/root — is a Single Type. A component that RECEIVES its content per
+  page (props/children vary) is a Component, however many pages render it.
+- **The Pricing page's plan tiers are the litmus test:** neither a Collection
+  (not managed like blog posts) nor a Single (their content is page-specific) —
+  a repeatable `Tier` **block** on the Pricing Single.
+- **A page in the Studio shows all its content top to bottom, header to
+  footer.** The Single Types a page references render inline in its page view;
+  editing one there edits it on every page that includes it — a virtual
+  reference, not a copy.
+- **The decision interview already answered the sensitive calls.** When
+  `fimo migrate wrap` ran, it asked the site owner the two questions detection
+  can't settle on its own, and LOCKED the answers in
+  `.fimo/migration/manifest.json`. Your agent prompt relays them under **LOCKED
+  DECISIONS** — execute them, never re-decide:
+  - **Illustration vs content** — a component that reproduces a UI in code (a
+    product screenshot/mock, a fake dashboard, a device frame, an animated
+    terminal/code demo) carries many tiny strings that belong to the
+    ILLUSTRATION, not to editable content. The owner marked which sections to
+    DROP: the machine already removed them from the CMS (labels stripped, seeded
+    rows deleted) and excludes their file on re-runs — do NOT model them or
+    re-add labels. Sections the owner kept as CONTENT stay in the model.
+  - **Content-model shape** — for a component rendered on 2+ pages that
+    detection left as a default Component (identical but copy-pasted into
+    different files), the owner classified it: SINGLE TYPE (same content
+    everywhere — model once, reference it), COLLECTION TYPE (repeated managed
+    entries), or COMPONENT (per-page content). Apply the classification exactly.
+    If a LOCKED DECISION is missing for a genuinely ambiguous section (an older
+    migration, or a decision recorded as `decidedBy: "default"`), surface it in
+    your report rather than guessing.
+
+Then, mechanically:
 
 - **Chrome** (header, footer, nav, menus, banners) is edited as ONE thing →
   a SINGLE TYPE per piece (`src/schemas/<Name>.json` with
@@ -103,17 +150,34 @@ A site's content model must read like a CMS, not like an implementation:
   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.
+  When a collection carries a field naming WHICH PAGE each entry belongs to
+  (one `FaqItem` collection whose rows are tagged `"about"`, `"pricing"`, …),
+  that field is `{"type": "string", "format": "page"}`, NEVER a bare
+  `{"type": "string"}`. `format: "page"` stores a registry page id and the
+  Studio renders a select of real pages instead of a free-text box — a
+  free string is a typo waiting to point at a page that does not exist.
 - **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.
+- **A page's SECTIONS are its Single's nested blocks — blocks STRUCTURE the
+  page, this is not optional.** 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). Blocks are what make a page
+  EDITABLE: in the Studio a block is a COLLAPSIBLE group, so a human edits the
+  "Testimonials" block, not thirty loose fields. **A rich page dumped as a
+  FLAT PILE of individual labels (`faq`, `commonQuestions`, `10x`,
+  `fasterToLaunch`, `guillermoRauch`, `ceoVercel`, …) is a FAILED migration
+  even when every string is captured** — it is unnavigable, uncollapsible,
+  overwhelming, and nobody can contribute. Group them: a testimonial's
+  quote + author + role + logo is ONE repeatable `testimonials` block item, not
+  four sibling labels; a stat's value + label is one `stats` item; the FAQ is
+  one `faq` block of question + answer items. 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. Adopt the machine-built page Single (it already has this block
+  structure); do NOT re-flatten it into labels. 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

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-29T15:37:14.073Z",
+  "bundledAt": "2026-07-30T17:19:28.475Z",
   "cliVersion": "0.8.0",
   "external": [
     "oxc-parser",