@se-studio/contentful-cms 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/contentful-cms Changelog
 
+## 1.0.6
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
+## 1.0.5
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.4
 
 ### Patch Changes

package/README.md

@@ -231,6 +231,8 @@ Capture a PNG of a component, collection, external component, person, or page. *
 
 Use `--out before.png` / `--out after.png` with `agent-browser diff screenshot` for visual diffing. See the **screenshots** skill for details.
 
+**Batch screenshots:** The `cms-capture-screenshots` script (same package) captures multiple variants to `<app-dir>/docs/cms-guidelines/screenshots/`. Run it from the **monorepo root** so the output path is correct: `node packages/contentful-cms/dist/bin/cms-capture-screenshots.js --variants /tmp/type-variants.json --app-dir apps/example-se2026`.
+
 ### export-converted
 
 Export a session ref's entry as **converted (`IBase*`) JSON** via the app's convert API. Use the output with `screenshot --json-file` for custom variants without a session.

package/dist/config/load.js

@@ -41,7 +41,7 @@ export function loadConfig(configPath) {
             environment: resolveEnvToken(space.environment),
             managementToken: resolveEnvToken(space.managementToken),
             defaultLocale: space.defaultLocale || 'en-US',
-            ...(space.devBaseUrl ? { devBaseUrl: space.devBaseUrl } : {}),
+            ...(space.devBaseUrl ? { devBaseUrl: resolveEnvToken(space.devBaseUrl) } : {}),
         };
     }
     return resolved;

package/dist/config/load.js.map

@@ -1 +1 @@
-{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/config/load.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",
@@ -36,7 +36,7 @@
     "@biomejs/biome": "^2.4.6",
     "@types/node": "^22.19.15",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
   "keywords": [
     "contentful",

package/skills/cms-guidelines/README.md

@@ -0,0 +1,140 @@
+# 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/cms-showcase/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/   # one .json per component (variant screenshots)
+    screenshots/         # screenshot PNGs (not committed; captured during pipeline)
+```

package/skills/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/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.json`
+   and the screenshots are committed to `docs/cms-guidelines/screenshots/`.

package/skills/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/hero-*.png` |
+| Accepted variant list | `generated/cms-discovery/accepted-variants/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/<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/cms-guidelines/generation-prompt.md

@@ -0,0 +1,202 @@
+# 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` |
+| Accepted screenshots | `generated/cms-discovery/accepted-variants/<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/<type-slug>.json):
+<ACCEPTED_VARIANTS_JSON>
+
+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 and typography class names (h1–h6, p2, p3).
+
+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>
+
+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.
+
+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)
+
+## 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)
+
+## Screenshots to capture
+(list of recommended variants for future captures)
+
+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 (h1–h6, p2, p3, h4) and colour names from the palette
+  as code-like snippets. Everything else is plain English.
+- 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 to capture"; describe parameters (props) instead.
+
+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/mapping.md
+- generated/cms-discovery/accepted-variants/<type-slug>.json
+- 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.
+
+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>"
+```

package/skills/cms-guidelines/validation-prompt.md

@@ -0,0 +1,170 @@
+# Validation Prompt — Guideline vs Code
+
+**Step 5.3 — LLM validation of a guideline fragment against the component source.**
+
+Run as part of the generation pipeline (not CI). Heavy validation that checks completeness
+and consistency before committing. It is acceptable for this to take time — correctness is
+the priority.
+
+---
+
+## When to run
+
+After Step 5.1 (generation) produces a guideline fragment, before committing. Feed the
+fragment and the component source to this prompt.
+
+---
+
+## Prompt
+
+```
+You are validating a CMS component guideline fragment for accuracy and completeness.
+
+You will be given:
+1. The guideline fragment (markdown).
+2. The component source file (TypeScript/React).
+3. Supporting files: SizingInformation.ts, Section.tsx, mapping.md.
+
+Your task: systematically check whether the guideline is COMPLETE and CONSISTENT with
+the code. Produce a detailed report.
+
+Guideline fragment:
+<GUIDELINE_MARKDOWN>
+
+Component source:
+<COMPONENT_SOURCE>
+
+SizingInformation.ts:
+<SIZING_SOURCE>
+
+Section.tsx:
+<SECTION_SOURCE>
+
+mapping.md (CMS field → app prop mapping):
+<MAPPING_SOURCE>
+
+---
+
+Check the following and report each as PASS, FAIL, or N/A:
+
+1. FIELDS COVERAGE
+   - Are all fields in USED_FIELDS mentioned in the "Used fields" table?
+   - Are any fields mentioned in the table that are NOT in USED_FIELDS?
+
+2. FIELD DESCRIPTIONS
+   - For each field in the table: is the "Effect when set" accurate?
+   - For each field in the table: is the "Effect when empty/removed" accurate?
+   - Are any effects described that do not match the code?
+
+3. TYPOGRAPHY
+   - Does the guideline state the correct typography class for each element?
+     (e.g. heading = h4, body = p3)
+   - Does it correctly describe which HTML element the heading renders as
+     based on index (h1 for first, h2 for later)?
+
+4. COLOUR BEHAVIOUR
+   - Does the guideline correctly describe how backgroundColour and textColour are applied
+     (section-wide, card-level, or neither)?
+   - Are the valid enum values for backgroundColour and textColour correct?
+
+5. POSITION/INDEX BEHAVIOUR
+   - If the component uses getSizingInformation(index), does the guideline describe:
+     (a) the heading level change (h1 vs h2)?
+     (b) the spacing/padding change?
+
+6. VARIANT DIFFERENCES
+   - If there are multiple registered variants (e.g. Hero and Hero Flipped), are they
+     all described, and are the differences accurately stated?
+
+7. IMPACT SECTION
+   - Does the "Impact of content changes" section describe what happens when:
+     (a) important optional fields are added?
+     (b) important optional fields are removed?
+   - Are there missing impact scenarios that would be confusing to a user?
+
+8. NO CODE REFERENCES
+   - Does the guideline contain any file path references (e.g. "Hero.tsx", "Section.tsx")?
+   - Does it contain any code beyond typography class names and colour names?
+
+9. COMPLETENESS
+   - Is there anything important in the code that the guideline does NOT mention and SHOULD?
+   - List any missing items.
+
+---
+
+Output format:
+
+## Validation Report — <ComponentType>
+
+### Summary
+PASS / FAIL / PARTIAL — one sentence overall verdict.
+
+### Checks
+
+| Check | Result | Detail |
+|---|---|---|
+| Fields coverage | PASS | All 10 used fields are in the table. |
+| Field descriptions | FAIL | `visual` empty description says "copy-only" but should say "copy spans full width". |
+| Typography | PASS | Heading h4, body p3 — correct. |
+| Colour behaviour | PASS | Section-wide application described correctly. |
+| Position/index | PASS | h1/h2 and padding described. |
+| Variant differences | PASS | Hero Flipped column order described. |
+| Impact section | PARTIAL | Removing preHeading described; removing body not described. |
+| No code references | PASS | No file paths or raw code. |
+| Completeness | PARTIAL | Animation behaviour (animate-when-seen) not mentioned. |
+
+### Issues to fix
+
+List each FAIL and PARTIAL item with a specific fix instruction:
+- **Field: visual empty description** — change to: "Copy spans full section width on all breakpoints."
+- **Impact: removing body** — add row: "Remove body → body block disappears; links follow directly after heading/subtitle."
+- **Completeness: animation** — add to Behaviour section: "All text elements animate in when they scroll into view."
+
+### Verdict
+
+APPROVED — The guideline is complete and consistent. Minor fixes applied.
+OR
+NEEDS REVISION — Fix issues above before committing.
+```
+
+---
+
+## Acceptance criteria
+
+**Approved if:**
+- Fields coverage = PASS
+- Typography = PASS
+- Colour behaviour = PASS
+- No code references = PASS
+- No more than 2 PARTIAL items (and they are minor)
+
+**Needs revision if:**
+- Any FAIL item
+- More than 2 PARTIAL items
+
+When revision is needed: apply the specific fixes from the "Issues to fix" list and re-run
+validation. Repeat until approved.
+
+---
+
+## Cursor agent task prompt
+
+```
+Validate the CMS guideline fragment for <COMPONENT_TYPE>.
+
+Files to read:
+- docs/cms-guidelines/components/<type-slug>.md (the guideline to validate)
+- src/project/components/<TypeName>.tsx (source of truth)
+- src/lib/SizingInformation.ts
+- src/framework/Section.tsx
+- generated/cms-discovery/mapping.md
+
+Follow the validation prompt in validation-prompt.md.
+Produce a validation report.
+
+If APPROVED: proceed to merge.
+If NEEDS REVISION: apply the specific fixes to docs/cms-guidelines/components/<type-slug>.md,
+then re-validate (run this task again with the updated fragment).
+When approved, run: pnpm run cms-guidelines:merge
+Then commit both files.
+```

package/skills/cms-guidelines/variant-loop.md

@@ -0,0 +1,184 @@
+# Variant Loop — Orchestrator
+
+**Step 4.4 — Orchestration of: propose → screenshot → evaluate.**
+
+This document describes the full variant loop for one CMS type. Run it as a **Cursor agent task**,
+or manually follow the steps below.
+
+---
+
+## Overview
+
+```
+ ┌──────────────────────────────────────────────────┐
+ │ INPUT: typeName, source file path, N             │
+ └──────────────────────┬───────────────────────────┘
+                        │
+                        ▼
+ ┌──────────────────────────────────────────────────┐
+ │ Step 1: Propose N variants (LLM)                 │
+ │ → variants.json (typeName, variants[])           │
+ └──────────────────────┬───────────────────────────┘
+                        │
+                        ▼
+ ┌──────────────────────────────────────────────────┐
+ │ Step 2: Capture screenshots                      │
+ │ → docs/cms-guidelines/screenshots/<name>.png     │
+ └──────────────────────┬───────────────────────────┘
+                        │
+                        ▼
+ ┌──────────────────────────────────────────────────┐
+ │ Step 3: Evaluate screenshot diversity (LLM)      │
+ │ → suitablyDifferent, acceptedVariants, rejected  │
+ └──────────────────────┬───────────────────────────┘
+                        │
+           ┌────────────┴─────────────┐
+           │ suitablyDifferent?       │
+           ▼ YES                      ▼ NO + attempts < 2×N
+ ┌──────────────────┐      ┌──────────────────────────────┐
+ │ Accept set;      │      │ Capture suggested new        │
+ │ proceed to gen  │      │ variants; re-evaluate         │
+ └──────────────────┘      └──────────────────────────────┘
+                                       │ attempts >= 2×N
+                                       ▼
+                            ┌──────────────────────────┐
+                            │ Accept best set so far   │
+                            └──────────────────────────┘
+```
+
+---
+
+## Cursor agent task
+
+**Assign this task to a Cursor subagent.** Provide:
+- `apps/example-brightline/src/project/components/<TypeName>.tsx` (component source)
+- `generated/cms-discovery/field-list.json` (field metadata including enum values)
+- `scripts/guidelines/variant-proposal-prompt.md` (variant proposal instructions)
+- `scripts/guidelines/evaluation-prompt.md` (evaluation instructions)
+- `scripts/guidelines/capture-screenshots.mjs` (screenshot tool)
+- This file (orchestration rules)
+
+**Task prompt:**
+
+```
+Run the variant loop for <TypeName>:
+
+1. PROPOSE: Read the component source file and field list. Using the instructions in
+   scripts/guidelines/variant-proposal-prompt.md, produce a variants.json for <TypeName>.
+   Use N = 5 (or fewer if the component is simple).
+
+2. CAPTURE: Run:
+     node scripts/guidelines/capture-screenshots.mjs --variants /tmp/variants.json
+   This saves screenshots to docs/cms-guidelines/screenshots/.
+
+3. EVALUATE: Using the instructions in scripts/guidelines/evaluation-prompt.md, look at
+   the captured screenshots and produce an evaluation JSON.
+   - If suitablyDifferent = true: proceed to Step 4.
+   - If suitablyDifferent = false AND total attempts < 2 × N:
+     Extend variants.json with 1–2 new variants from the suggestions, capture them,
+     re-evaluate. Repeat until suitablyDifferent = true or 2×N total attempts.
+   - If 2×N attempts reached: accept the best acceptedVariants set seen.
+
+4. WRITE ACCEPTED LIST: Save the final accepted variant list to:
+   generated/cms-discovery/accepted-variants/<type-slug>.json
+   Format: { "typeName": "<TypeName>", "acceptedVariants": [...] }
+
+5. COMMIT: git add docs/cms-guidelines/screenshots/ generated/cms-discovery/
+           git commit -m "chore(bl): variant screenshots for <TypeName>"
+```
+
+---
+
+## Manual steps
+
+If running manually:
+
+### 1 — Propose variants
+
+Feed the component source file to an LLM with the prompt in
+`scripts/guidelines/variant-proposal-prompt.md`.
+
+Save the output as `/tmp/<type-slug>-variants.json`.
+
+Example for Hero:
+```json
+{
+  "typeName": "Hero",
+  "mode": "component",
+  "variants": [
+    { "label": "default", "description": "All fields.", "showcaseParams": {} },
+    { "label": "no-visual", "description": "No visual.", "showcaseParams": { "showVisual": "false" } },
+    { "label": "navy", "description": "Navy bg.", "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" } },
+    { "label": "pine", "description": "Pine bg.", "showcaseParams": { "backgroundColour": "Pine", "textColour": "Off White" } },
+    { "label": "minimal", "description": "Heading only.", "showcaseParams": { "showVisual": "false", "showLinks": "false" } }
+  ]
+}
+```
+
+### 2 — Capture screenshots
+
+```bash
+# From apps/example-brightline
+node scripts/guidelines/capture-screenshots.mjs --variants /tmp/hero-variants.json
+```
+
+Saves to `docs/cms-guidelines/screenshots/hero-*.png`.
+
+### 3 — Evaluate
+
+Feed the screenshots + evaluation prompt to an LLM. The LLM looks at the images and
+returns `suitablyDifferent`, `acceptedVariants`, `rejectedVariants`, and `suggestions`.
+
+If not suitably different: replace rejected screenshots with suggestions, re-capture, re-evaluate.
+
+### 4 — Save accepted list
+
+```bash
+mkdir -p generated/cms-discovery/accepted-variants
+# Write manually or via script
+```
+
+### 5 — Commit
+
+```bash
+git add docs/cms-guidelines/screenshots/ generated/cms-discovery/accepted-variants/
+git commit -m "chore(bl): variant screenshots for Hero"
+```
+
+---
+
+## accepted-variants JSON format
+
+```json
+{
+  "typeName": "Hero",
+  "generatedAt": "2026-03-12",
+  "acceptedVariants": [
+    {
+      "label": "default",
+      "description": "All fields populated, no colour override.",
+      "screenshotPath": "docs/cms-guidelines/screenshots/hero-default.png",
+      "showcaseParams": {}
+    },
+    {
+      "label": "navy",
+      "description": "Navy background + Off White text.",
+      "screenshotPath": "docs/cms-guidelines/screenshots/hero-navy.png",
+      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
+    }
+  ]
+}
+```
+
+This file is read by the generation step (Phase 5) to know which screenshots to include
+in the guideline prompt.
+
+---
+
+## Notes
+
+- Collections use `--collection <TypeName>` in cms-edit. The capture script handles this via `mode`.
+- If `agent-browser` is not installed, the capture script degrades to URL-only output; run
+  `agent-browser install` to enable actual screenshot capture.
+- The variant loop is the most expensive step. For simple components (1–2 visual states),
+  N = 3 is usually sufficient.

package/skills/cms-guidelines/variant-proposal-prompt.md

@@ -0,0 +1,127 @@
+# Variant Proposal Prompt
+
+**Step 4.1 — Input/output contract and prompt for proposing component variants.**
+
+The variant loop produces screenshots that cover the visual diversity of a component. A good
+set captures: default state, important absent-field states, colour variants, and any layout
+variants (like flipped). The screenshots are then used to write the "What it looks like" and
+"Colours" sections of the guideline.
+
+---
+
+## Input
+
+- **Component source file:** full contents of `src/project/components/<Type>.tsx` (or
+  `src/project/collections/<Type>.tsx`).
+- **Used fields:** the `USED_FIELDS` or `FIELD_KEYS` from the source file.
+- **Palette:** `backgroundColour` and `textColour` enum values from `generated/cms-discovery/field-list.json`
+  (or from `generated/colors.ts`).
+- **N:** number of variants to propose (typically 4–6 for a component, up to 8 for complex ones).
+
+The LLM should output **N variants** in JSON format (see below).
+
+---
+
+## Prompt
+
+```
+You are preparing screenshots for CMS component guidelines.
+
+I will give you the source code of a Next.js component that renders a CMS entry.
+Your task: propose N variants that, together, best document how the component looks
+under different conditions. Choose variants that are VISUALLY DISTINCT — a reader
+should be able to tell them apart at a glance.
+
+Component source:
+<COMPONENT_SOURCE>
+
+Palette (backgroundColour options):
+<BACKGROUND_COLOURS>
+
+Text colour options (textColour):
+<TEXT_COLOURS>
+
+Rules:
+1. Always include a "default" variant with all optional fields populated and no colour override.
+2. Include at least one variant per important "missing field" state (e.g. no visual, no links).
+3. Include at least one colour variant if the component has backgroundColour (use a dark colour
+   like Navy or Deep Periwinkle).
+4. If the component has a flipped/alternate variant (e.g. Hero Flipped), include it.
+5. Avoid variants that will look identical or near-identical to another variant in the list.
+6. N = <N>; produce exactly N variants (or fewer if the component is simple).
+
+Output JSON only, no explanation. Format:
+{
+  "typeName": "<CMS componentType or collectionType>",
+  "variants": [
+    {
+      "label": "default",
+      "description": "All fields populated, no colour override.",
+      "showcaseParams": {}
+    },
+    {
+      "label": "no-visual",
+      "description": "visual field removed; copy spans full width.",
+      "showcaseParams": { "showVisual": "false" }
+    },
+    {
+      "label": "navy-background",
+      "description": "Navy background with Off White text.",
+      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
+    }
+  ]
+}
+
+showcaseParams keys must match the cms-edit screenshot --param format:
+  backgroundColour, textColour, showVisual, showLinks, showHeading, etc.
+For a flipped variant, use a separate typeName entry for "Hero Flipped".
+```
+
+---
+
+## Output contract
+
+```json
+{
+  "typeName": "Hero",
+  "variants": [
+    {
+      "label": "default",
+      "description": "All optional fields populated, no colour override.",
+      "showcaseParams": {}
+    },
+    {
+      "label": "no-visual",
+      "description": "Visual removed; copy spans full width.",
+      "showcaseParams": { "showVisual": "false" }
+    },
+    {
+      "label": "navy",
+      "description": "Navy background + Off White text.",
+      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
+    },
+    {
+      "label": "minimal",
+      "description": "Heading only, no eyebrow/subtitle/body/links/visual.",
+      "showcaseParams": { "showVisual": "false", "showLinks": "false" }
+    }
+  ]
+}
+```
+
+- `label` — used to name the screenshot file: `<typeName-kebab>-<label>.png`
+- `description` — included in the screenshot log and used by the evaluation step
+- `showcaseParams` — key-value pairs passed as `--param key=value` to `cms-edit screenshot`
+
+---
+
+## Notes on N and the cap
+
+The orchestrator (Step 4.4) uses N (the number of proposed variants) as a cap:
+
+- It will attempt up to **2×N** screenshots in total.
+- If the evaluation step (Step 4.3) concludes the variants are "suitably different" before
+  reaching 2×N attempts, it stops early.
+- If not, it requests a new proposal from the LLM for the remaining slots (up to 2×N total).
+
+For most components, N = 4–6 produces a good coverage set.