@se-studio/project-build 1.0.105 → 1.0.107

package/skills/contentful-cms/cms-guidelines/README.md

@@ -0,0 +1,147 @@
+# CMS Guidelines Generation
+
+This directory contains the pipeline prompts and documentation for generating CMS component guideline fragments for any app in the monorepo.
+
+---
+
+## What are CMS guidelines?
+
+Guidelines are short markdown fragments — one per CMS type — that describe how each component or collection looks, what fields it uses, how colours are applied, and how it behaves. They are merged into `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`, a single document used to give LLMs accurate context about the app's component library.
+
+---
+
+## Lifecycle: From content to guidelines
+
+1. **Build the site** — implement all components and collections; ensure all content is correct and published in Contentful.
+2. **Generate showcase data** — pull real Contentful data into the app's showcase:
+   ```bash
+   pnpm --filter <appName> generate-showcase
+   ```
+   This writes `src/generated/showcase-examples.json`.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](.cursor/skills/se-marketing-sites/curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+4. **Generate field list** — parse TypeScript types to produce structured field metadata:
+   ```bash
+   # From the app directory:
+   pnpm run cms-discovery:field-list
+
+   # Or from repo root:
+   pnpm --filter <appName> exec cms-generate-field-list --app-dir .
+   ```
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md).
+
+Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
+
+---
+
+## How to run guideline generation
+
+Use the Cursor skill at [`.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md`](.cursor/skills/contentful-cms/generate-cms-guidelines/SKILL.md). It supports three modes:
+
+| Mode | When to use |
+|---|---|
+| `full` | First-time generation, or regenerate everything |
+| `single` | Regenerate one component after code changes |
+| `merge-only` | Rebuild `COMPONENT_GUIDELINES_FOR_LLM.md` after manual fragment edits |
+
+**Example: full from scratch for `example-om1`**
+
+Start the app:
+```bash
+pnpm --filter example-om1 dev
+```
+
+Then invoke the skill with:
+- App directory: `apps/example-om1`
+- Mode: `full`
+- Discovery URL: `http://localhost:3013/api/cms/discovery/`
+
+**Example: single component**
+
+Invoke the skill with:
+- App directory: `apps/example-se2026`
+- Mode: `single`
+- Type name: `Hero`
+- Discovery URL: `http://localhost:3012/api/cms/discovery/`
+
+**Example: merge only**
+
+```bash
+cms-merge-guidelines --app-dir apps/example-om1
+```
+
+---
+
+## CLIs used by this pipeline
+
+| CLI | Purpose |
+|---|---|
+| `cms-generate-field-list` | Parse TypeScript types → `field-list.json` |
+| `cms-capture-screenshots` | Capture component screenshots for variant evaluation |
+| `cms-update-colour-hints` | Upsert a colour hint in `colour-hints.json` |
+| `cms-generate-collection-guidelines` | **New** — generate all collection/external `.md` files from a discovery URL |
+| `cms-merge-guidelines` | Merge all fragments → `COMPONENT_GUIDELINES_FOR_LLM.md` |
+
+All CLIs are provided by `@se-studio/contentful-cms`. Run `pnpm build` from the repo root to ensure they are built and linked.
+
+---
+
+## `cms-generate-collection-guidelines`
+
+New project-independent CLI. Reads the discovery API and writes collection and external guideline fragments without any app-specific hardcoding.
+
+```bash
+cms-generate-collection-guidelines \
+  --discovery-url http://localhost:3010/api/cms/discovery/ \
+  --app-dir apps/example-brightline
+```
+
+Options:
+
+| Flag | Description |
+|---|---|
+| `--discovery-url <url>` | Discovery API URL (required). App must be running. |
+| `--app-dir <path>` | App directory (default: cwd). |
+
+Outputs:
+- `docs/cms-guidelines/collections/<slug>.md` for every collection
+- `docs/cms-guidelines/externals/<slug>.md` for every external
+- Updates `generated/cms-discovery/colour-hints.json`
+
+---
+
+## Pipeline document index
+
+| File | Purpose |
+|---|---|
+| `generate-component-guidelines.md` | Full pipeline overview: Phases A–F |
+| `variant-loop.md` | Phase A: propose variants → screenshot → evaluate |
+| `variant-proposal-prompt.md` | LLM prompt: propose showcase variants |
+| `evaluation-prompt.md` | LLM prompt: evaluate screenshot diversity |
+| `generation-prompt.md` | Phase B: three-step guideline generation |
+| `colour-hint-prompt.md` | Phase C: derive colour application hint |
+| `validation-prompt.md` | Phase D: 9-check guideline validation |
+
+---
+
+## Output files (per app)
+
+```
+<appDir>/
+  docs/cms-guidelines/
+    components/          # one .md per componentType
+    collections/         # one .md per collectionType
+    externals/           # one .md per externalComponentType
+    COMPONENT_GUIDELINES_FOR_LLM.md   # merged document
+  generated/cms-discovery/
+    field-list.json
+    colour-hints.json
+    accepted-variants/
+      components/        # one .json per component type
+      collections/       # one .json per collection type
+      externals/         # one .json per external component type
+    screenshots/
+      components/        # PNG screenshots for components
+      collections/       # PNG screenshots for collections
+      externals/         # PNG screenshots for externals
+      index.json         # file field uses subpath e.g. "components/hero-default.png"
+```

package/skills/contentful-cms/cms-guidelines/colour-hint-prompt.md

@@ -0,0 +1,77 @@
+# Colour Hint Prompt
+
+**Step 5.2 — Produce a structured colour hint per CMS type.**
+
+The colour hint is a short machine-readable label describing how `backgroundColour` and
+`textColour` are applied in this component. It is stored in
+`generated/cms-discovery/colour-hints.json` and served by the discovery API.
+
+---
+
+## Purpose
+
+The colour hint helps tools and LLMs quickly understand how colours work without reading
+the full guideline. For example:
+
+- `"section"` → the colour applies to the full-width section (both copy and visual columns).
+- `"card"` → the colour is applied per-card inside a collection.
+- `"none"` → this type does not use backgroundColour/textColour.
+
+---
+
+## Valid hint values
+
+| Value | Meaning |
+|---|---|
+| `"section"` | backgroundColour/textColour apply to the full-width section wrapper (most components) |
+| `"card"` | Colours apply per-card (collection items); section has no colour |
+| `"section+card"` | Both section-level and card-level colours exist |
+| `"none"` | The type does not use backgroundColour or textColour |
+
+---
+
+## Prompt (to run as part of generation)
+
+```
+You are writing a colour hint for a CMS component documentation system.
+
+Component: <COMPONENT_TYPE>
+Component source:
+<COMPONENT_SOURCE>
+
+Section.tsx source (shows how backgroundColour/textColour are applied at section level):
+<SECTION_SOURCE>
+
+Look at how backgroundColour and textColour are used in the source.
+
+Rules:
+- If backgroundColour/textColour are in USED_FIELDS AND passed to a Section wrapper (or
+  similar full-width wrapper): hint = "section"
+- If backgroundColour/textColour are applied per-card in a collection: hint = "card"
+- If both are true: hint = "section+card"
+- If neither backgroundColour nor textColour is in USED_FIELDS: hint = "none"
+
+Output JSON only:
+{
+  "typeName": "<COMPONENT_TYPE>",
+  "colourApplication": "section",
+  "notes": "backgroundColour and textColour applied to the full Section wrapper."
+}
+```
+
+---
+
+## Script to update colour-hints.json
+
+Run the script after generating each component:
+
+```bash
+cms-update-colour-hints --type "Hero" --hint "section" \
+  --notes "backgroundColour and textColour applied to the full Section wrapper."
+```
+
+Or provide an LLM-generated JSON file:
+
+```bash
+cms-update-colour-hints --from /tmp/hero-colour-hint.json
+```

package/skills/contentful-cms/cms-guidelines/evaluation-prompt.md

@@ -0,0 +1,84 @@
+# Evaluation Prompt — Screenshot Differences
+
+**Step 4.3 — Prompt for evaluating whether captured screenshots are suitably different.**
+
+The evaluation step is used by the orchestrator (Step 4.4) to decide whether to accept the
+current set of screenshots, or to request additional variants (up to the 2×N cap).
+
+---
+
+## When to run
+
+After `cms-capture-screenshots` has captured a batch of screenshots, feed them to an LLM with
+this prompt. The LLM inspects the images and returns a verdict.
+
+---
+
+## Prompt
+
+```
+You are reviewing a set of component screenshots for CMS documentation purposes.
+
+Your task: decide whether this set of screenshots is "suitably different" — meaning
+each screenshot looks visually distinct enough that a reader could tell them apart,
+and together they cover the important visual states of the component.
+
+Component: <COMPONENT_TYPE>
+Screenshots (attached as images):
+<LIST OF {label, path, description} PAIRS>
+
+Rules:
+1. Two screenshots are "not different enough" if they look nearly identical — same layout,
+   same colours, same content, just minor text length differences.
+2. The set is "suitably different" if:
+   - At least two screenshots have clearly different layouts (e.g. one has a visual, one does not), OR
+   - At least two screenshots have clearly different colour schemes (e.g. one light, one dark), OR
+   - At least two screenshots show clearly different content (e.g. one full, one minimal).
+3. A set with only one screenshot is NEVER "suitably different" — we need at least two variants.
+
+Output JSON only:
+{
+  "suitablyDifferent": true,
+  "reason": "Short explanation of why the set is or is not diverse enough.",
+  "acceptedVariants": ["default", "navy", "no-visual"],
+  "rejectedVariants": ["minimal"],
+  "suggestions": [
+    "The 'minimal' variant looks too similar to 'no-visual'. Try a variant with a tinted background
+     instead, e.g. Pine background."
+  ]
+}
+
+- acceptedVariants: labels of screenshots that are good to keep.
+- rejectedVariants: labels that are too similar to others or not useful.
+- suggestions: optional list of new variant ideas to try if suitablyDifferent is false
+  (or if any variant was rejected).
+- If suitablyDifferent is true, suggestions can be empty.
+```
+
+---
+
+## Output contract
+
+```json
+{
+  "suitablyDifferent": true,
+  "reason": "The default and navy variants have clearly different colour schemes. The no-visual variant shows a different layout. Together they document the main visual states.",
+  "acceptedVariants": ["default", "navy", "no-visual"],
+  "rejectedVariants": ["minimal"],
+  "suggestions": [
+    "Consider replacing 'minimal' with a Pine background variant to show a green colour scheme."
+  ]
+}
+```
+
+---
+
+## How the orchestrator uses this
+
+1. If `suitablyDifferent === true` AND all variants are accepted → stop; use the accepted set.
+2. If `suitablyDifferent === false` OR any variants were rejected:
+   - If `attempts < 2 × N` → use `suggestions` to generate additional variant params; capture
+     the new screenshots; re-evaluate.
+   - If `attempts >= 2 × N` → stop; use `acceptedVariants` from the best evaluation so far.
+3. The final accepted set is written to `generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json`
+   and the screenshots are committed to `docs/cms-guidelines/screenshots/{components|collections|externals}/`.

package/skills/contentful-cms/cms-guidelines/generate-component-guidelines.md

@@ -0,0 +1,126 @@
+# Generate Component Guidelines — Full Pipeline (Step 5.4)
+
+**End-to-end pipeline for one component:** variant loop → generate → colour hint → validate → merge → commit.
+
+---
+
+## What this produces
+
+For one CMS type (e.g. Hero):
+
+| Output | Location |
+|---|---|
+| Variant screenshots | `docs/cms-guidelines/screenshots/components/hero-*.png` |
+| Accepted variant list | `generated/cms-discovery/accepted-variants/components/hero.json` |
+| Guideline fragment | `docs/cms-guidelines/components/hero.md` |
+| Colour hint entry | `generated/cms-discovery/colour-hints.json` |
+| Merged full doc (updated) | `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` |
+
+---
+
+## Cursor agent task prompt
+
+**Assign to a Cursor subagent. Provide:**
+- This file
+- `variant-loop.md` (in the same skills/cms-guidelines/ directory)
+- `generation-prompt.md`
+- `colour-hint-prompt.md`
+- `validation-prompt.md`
+- `docs/cms-guidelines/LAYOUT.md`
+- `tmp/component-guidelines-target-format.md`
+
+**Task prompt:**
+
+```
+Run the full guideline generation pipeline for <COMPONENT_TYPE>.
+Target app: <APP_DIR> (all paths relative to that directory).
+
+=== Phase A: Variant loop ===
+Follow variant-loop.md.
+1. Read src/project/components/<TypeName>.tsx (or collections/<TypeName>.tsx).
+2. Read generated/cms-discovery/field-list.json for field metadata.
+3. Propose N=5 variants using the prompt in variant-proposal-prompt.md.
+4. Capture screenshots:
+   cms-capture-screenshots --variants /tmp/<type-slug>-variants.json --app-dir <APP_DIR>
+5. Evaluate screenshots using evaluation-prompt.md.
+   - If not suitably different and attempts < 2×N: capture new suggestions, re-evaluate.
+   - When done: save accepted list to generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
+
+=== Phase B: Generate guideline ===
+Follow generation-prompt.md.
+1. Describe screenshots (Step 1 prompt).
+2. Extract behaviour from code (Step 2 prompt).
+3. Merge into guideline block (Step 3 prompt).
+4. Save output to docs/cms-guidelines/components/<type-slug>.md.
+   (Collections → collections/<type-slug>.md, externals → externals/<type-slug>.md)
+
+=== Phase C: Colour hint ===
+Follow colour-hint-prompt.md.
+Derive the colour application hint (section/card/section+card/none) from the source.
+Run:
+  cms-update-colour-hints --app-dir <APP_DIR> \
+    --type "<COMPONENT_TYPE>" --hint "<hint>" --notes "<brief reason>"
+
+=== Phase D: Validate ===
+Follow validation-prompt.md.
+1. Read the generated fragment and the component source.
+2. Run the 9-check validation.
+3. If NEEDS REVISION: apply fixes to the fragment and re-run validation.
+4. Repeat until APPROVED.
+
+=== Phase E: Merge ===
+  cms-merge-guidelines --app-dir <APP_DIR>
+This updates docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md.
+
+=== Phase F: Commit ===
+  git add docs/cms-guidelines/ generated/cms-discovery/
+  git commit -m "chore: generate guidelines for <COMPONENT_TYPE>"
+```
+
+---
+
+## Manual pipeline (for Hero — already partially done)
+
+Hero has a hand-written guideline fragment (Step 3.1), accepted variant screenshots
+(Step 4.2), and colour hints (Step 5.2). To complete the pipeline manually:
+
+```bash
+# Phase D: Validate hero.md (hand-written)
+# Use: validation-prompt.md + src/project/components/Hero.tsx
+# Apply any fixes to docs/cms-guidelines/components/hero.md
+
+# Phase E: Merge
+cms-merge-guidelines
+
+# Phase F: Commit
+git add docs/cms-guidelines/ generated/cms-discovery/
+git commit -m "chore: complete Hero guideline pipeline"
+```
+
+---
+
+## For all components (full site run)
+
+To generate guidelines for all components and collections:
+
+1. Get the list of all types from the discovery API:
+   ```
+   GET /api/cms/discovery
+   ```
+2. For each type in components[], collections[], externals[], run this pipeline.
+3. After all types: run merge and commit the final COMPONENT_GUIDELINES_FOR_LLM.md.
+
+A full run typically takes 5–10 minutes per component (mostly LLM time) and
+30–60 minutes total for a typical site.
+
+---
+
+## npm scripts summary
+
+| Script | What it does |
+|---|---|
+| `pnpm run cms-discovery:field-list` | Generate `generated/cms-discovery/field-list.json` from TypeScript types |
+| `pnpm run cms-guidelines:screenshots` | Capture screenshots for a type (interactive) |
+| `pnpm run cms-guidelines:merge` | Merge per-type files into COMPONENT_GUIDELINES_FOR_LLM.md |
+| `cms-update-colour-hints` | Upsert a colour hint in colour-hints.json |
+| `cms-capture-screenshots` | Capture screenshots for a type |

package/skills/contentful-cms/cms-guidelines/generation-prompt.md

@@ -0,0 +1,231 @@
+# Generation Prompt — Code + Screenshots → Guideline Block
+
+**Step 5.1 — Multi-step prompts for generating one guideline fragment.**
+
+Run as a **Cursor agent task**. The agent reads the component source, screenshots, and field
+metadata, then writes a self-contained markdown guideline fragment in the target format.
+
+---
+
+## Inputs
+
+| Input | Source |
+|---|---|
+| Component source file | `src/project/components/<TypeName>.tsx` |
+| Field metadata (used fields + types + enums) | `generated/cms-discovery/field-list.json` |
+| Project theme (palette + typography + grid) | `generated/cms-discovery/theme-context.md` |
+| Accepted screenshots | `generated/cms-discovery/accepted-variants/{components\|collections\|externals}/<type-slug>.json` + image files |
+| Target format example | `tmp/component-guidelines-target-format.md` (Hero example) |
+| Mapping reference | `generated/cms-discovery/mapping.md` |
+| SizingInformation source | `src/lib/SizingInformation.ts` |
+| Section wrapper source | `src/framework/Section.tsx` (for backgroundColour/textColour behaviour) |
+
+---
+
+## Step 1 of 3 — Describe the screenshots
+
+**Prompt:**
+
+```
+You are documenting a CMS component for a marketing site.
+
+I will give you screenshots of the component in different states, and the component's
+accepted variant list. Describe what you see in each screenshot.
+
+Component: <COMPONENT_TYPE>
+
+Accepted variants (from accepted-variants/{components|collections|externals}/<type-slug>.json):
+<ACCEPTED_VARIANTS_JSON>
+
+Project theme (from generated/cms-discovery/theme-context.md):
+<THEME_CONTEXT>
+
+For each variant, describe:
+- The visual layout (columns, stack, full-width, etc.)
+- The elements visible (heading, eyebrow, body, links, visual/image, background colour)
+- The typography appearance (large heading, small body text, etc.)
+- The colour scheme (background colour, text colour, whether the visual is tinted)
+- Anything notable (animations not applicable in screenshots, spacing gaps, alignment)
+
+Be precise. Write one short paragraph per variant (3–5 sentences). No code references.
+Only use colour names from the site palette (listed in the theme context above) and
+typography class names (h1–h6, p2, p3 etc. from the typography scale above).
+
+Output format: one section per variant, headed by ## <label>.
+```
+
+---
+
+## Step 2 of 3 — Extract behaviour and fields from code
+
+**Prompt:**
+
+```
+You are writing CMS component documentation.
+
+I will give you the source code of a Next.js component. Extract all behaviour
+rules for the documentation. Do NOT quote or reference the code — translate
+the code behaviour into plain English rules that a non-developer can follow.
+
+Component source:
+<COMPONENT_SOURCE>
+
+SizingInformation.ts source (shows how index affects heading level and section spacing):
+<SIZING_INFORMATION_SOURCE>
+
+Section.tsx source (shows how backgroundColour and textColour are applied):
+<SECTION_SOURCE>
+
+Field mapping reference (mapping.md — shows how CMS fields map to app props):
+<MAPPING_SOURCE>
+
+Project theme (palette, typography, grid from generated/cms-discovery/theme-context.md):
+<THEME_CONTEXT>
+
+Extract and write:
+1. FIELDS: For each field in USED_FIELDS, write one row: field name, type, what it does when
+   set, what happens when it is empty. Use only typography class names and colour names as
+   code snippets. No file paths.
+2. BEHAVIOUR: Any behaviour that depends on position (index), variant (flipped), or other
+   logic. E.g. "When this is the first block on the page, the heading renders as <h1>".
+3. IMPACT: What visually changes when content changes (longer text, add/remove visual, etc.).
+4. TYPOGRAPHY: Which typography classes (h1–h6, p2, p3, h4, etc.) are applied to each element.
+5. COLOUR APPLICATION: How backgroundColour and textColour are applied. Section-wide? Per-card?
+
+Output each section clearly labelled (## Fields, ## Behaviour, ## Impact, ## Typography,
+## Colour Application). No code blocks. No file references. Plain English only (except
+typography class names and colour names).
+```
+
+---
+
+## Step 3 of 3 — Merge into guideline block
+
+**Prompt:**
+
+```
+You are writing a self-contained CMS component guideline fragment.
+
+Below are two inputs:
+A) Screenshot descriptions for each variant of <COMPONENT_TYPE>.
+B) Extracted behaviour rules from the source code.
+
+Also provided:
+- The target format example (Hero guideline from tmp/component-guidelines-target-format.md).
+- The field list from generated/cms-discovery/field-list.json.
+- The project theme from generated/cms-discovery/theme-context.md (palette names + typography scale).
+- The screenshot index from docs/cms-guidelines/screenshots/index.json (lists captured screenshots).
+- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:3010").
+
+Produce a single markdown fragment for <COMPONENT_TYPE> following EXACTLY this structure:
+
+# <ComponentType>
+(one-line summary of what it is and when to use it)
+
+## Screenshots
+
+(For each accepted variant that has a captured screenshot in index.json, include an image link.
+Use the devBaseUrl from .contentful-cms.json for the host.
+Use the `file` field from index.json VERBATIM as the ?file= value — it may include a subdirectory
+prefix such as `components/` or `collections/`. Do NOT reconstruct the path from the type slug. Format:)
+
+| Variant | Preview |
+|---------|---------|
+| Default | ![Default](<devBaseUrl>/cms/screenshot?file=<file-field-from-index-json>) |
+| Navy    | ![Navy](<devBaseUrl>/cms/screenshot?file=<file-field-from-index-json>) |
+
+(Only include variants present in index.json. If no screenshots exist, write: "No screenshots captured yet. Run cms-capture-screenshots to generate them.")
+
+## What it looks like
+(describe layout, columns, stacking, visible elements — based on screenshot descriptions)
+
+## Typography
+(typography classes for heading, body, subtitle — bullets only)
+
+## Colours
+(how backgroundColour/textColour apply — section-wide? per-card? valid palette values)
+
+## Used fields
+(table: Field | Type | Effect when set | Effect when empty/removed)
+
+## Behaviour
+(position/index rules, variant differences, anything that depends on content logic)
+
+## Impact of content changes
+(table or bullets: what changes when you add/remove/change specific fields)
+
+Rules:
+- SELF-CONTAINED. A reader with no code access must fully understand the component.
+- No source code references, no file paths, no "see Hero.tsx".
+- Only use typography class names (from theme-context.md, e.g. h1–h6, p2, p3) and colour
+  names (from theme-context.md palette) as code-like snippets. Everything else is plain English.
+- For the ## Colours section, list the valid palette colour names from theme-context.md — do
+  NOT invent colour names or describe them generically.
+- If a field is listed in USED_FIELDS but has no visual effect when empty, say
+  "No visible effect when empty" in the table.
+- Collections: add a section for card-level fields and describe how the number of cards
+  affects layout.
+- External components: omit screenshots and the Screenshots section; describe parameters instead.
+- Screenshot links use the devBaseUrl from .contentful-cms.json — they resolve when the dev
+  server is running and are useful for both human reviewers and AI assistants.
+
+Output raw markdown only. Start with "# <ComponentType>". No preamble.
+```
+
+---
+
+## External component variant
+
+For external components (no showcase), replace Step 1 with:
+
+```
+The component has no screenshots (not yet in the showcase). Instead, describe what
+the component likely looks like based on its name and parameters alone. Mark this
+section with a note: "(Visual description estimated from code; no screenshots available.)"
+```
+
+All other steps are the same.
+
+---
+
+## After generation
+
+After the LLM produces the fragment:
+
+1. Save to `docs/cms-guidelines/components/<type-slug>.md`
+   (or `collections/` or `externals/` as appropriate).
+2. Run validation (Step 5.3 prompt).
+3. If validation passes, run merge: `pnpm run cms-guidelines:merge`
+4. Commit both files.
+
+---
+
+## Cursor agent task prompt
+
+```
+Generate the CMS guideline fragment for <COMPONENT_TYPE>.
+
+Files to read:
+- src/project/components/<TypeName>.tsx (or collections/<TypeName>.tsx)
+- generated/cms-discovery/field-list.json
+- generated/cms-discovery/theme-context.md (palette + typography + grid — use for all colour and font references)
+- generated/cms-discovery/mapping.md
+- generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
+- docs/cms-guidelines/screenshots/index.json (to know which screenshots exist)
+- .contentful-cms.json (to get devBaseUrl for screenshot links)
+- src/lib/SizingInformation.ts
+- src/framework/Section.tsx
+- tmp/component-guidelines-target-format.md (example format)
+
+Images to analyse:
+- docs/cms-guidelines/screenshots/<type-slug>-*.png (all accepted variant screenshots)
+
+Follow the three-step generation process in generation-prompt.md:
+1. Describe screenshots.
+2. Extract behaviour from code.
+3. Merge into guideline fragment (include ## Screenshots section with image links using devBaseUrl).
+
+Save the output to docs/cms-guidelines/components/<type-slug>.md.
+Then run: pnpm run cms-guidelines:merge
+Then commit: git add docs/cms-guidelines/ && git commit -m "chore(bl): generate guideline for <TypeName>"
+```