@se-studio/contentful-cms 1.0.3 → 1.0.5

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.