@se-studio/contentful-cms 1.0.12 → 1.0.13

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/contentful-cms Changelog
 
+## 1.0.13
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "CLI tool for AI agents to read and edit Contentful draft content without publish permissions",
   "repository": {
     "type": "git",

package/skills/cms-guidelines/README.md

@@ -135,6 +135,13 @@ Outputs:
   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)
+    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/cms-guidelines/evaluation-prompt.md

@@ -80,5 +80,5 @@ Output JSON only:
    - 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/`.
+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/cms-guidelines/generate-component-guidelines.md

@@ -10,8 +10,8 @@ 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` |
+| 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` |
@@ -44,7 +44,7 @@ Follow variant-loop.md.
    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
+   - 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.

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

@@ -13,7 +13,8 @@ metadata, then writes a self-contained markdown guideline fragment in the target
 |---|---|
 | 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 |
+| 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` |
@@ -33,9 +34,12 @@ accepted variant list. Describe what you see in each screenshot.
 
 Component: <COMPONENT_TYPE>
 
-Accepted variants (from accepted-variants/<type-slug>.json):
+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)
@@ -44,7 +48,8 @@ For each variant, describe:
 - 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).
+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>.
 ```
@@ -74,6 +79,9 @@ Section.tsx source (shows how backgroundColour and textColour are applied):
 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
@@ -105,6 +113,7 @@ 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").
 
@@ -116,12 +125,14 @@ Produce a single markdown fragment for <COMPONENT_TYPE> following EXACTLY this s
 ## 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. Format:)
+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=<type-slug>-default.png) |
-| Navy    | ![Navy](<devBaseUrl>/cms/screenshot?file=<type-slug>-navy.png) |
+| 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.")
 
@@ -146,8 +157,10 @@ Use the devBaseUrl from .contentful-cms.json for the host. Format:)
 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.
+- 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
@@ -195,8 +208,9 @@ 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/<type-slug>.json
+- 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

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

@@ -23,7 +23,7 @@ or manually follow the steps below.
                         ▼
  ┌──────────────────────────────────────────────────┐
  │ Step 2: Capture screenshots                      │
- │ → docs/cms-guidelines/screenshots/<name>.png     │
+ │ → docs/cms-guidelines/screenshots/{mode}s/<n>.png│
  └──────────────────────┬───────────────────────────┘
                         │
                         ▼
@@ -53,6 +53,7 @@ or manually follow the steps below.
 **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)
+- `generated/cms-discovery/theme-context.md` (palette + typography — authoritative colour names)
 - `scripts/guidelines/variant-proposal-prompt.md` (variant proposal instructions)
 - `scripts/guidelines/evaluation-prompt.md` (evaluation instructions)
 - `scripts/guidelines/capture-screenshots.mjs` (screenshot tool)
@@ -63,9 +64,10 @@ or manually follow the steps below.
 ```
 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).
+1. PROPOSE: Read the component source file, field list, and theme-context.md (for palette names).
+   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).
+   IMPORTANT: use only colour names from theme-context.md — do NOT invent colour names.
 
 2. CAPTURE: Run:
      node scripts/guidelines/capture-screenshots.mjs --variants /tmp/variants.json
@@ -80,8 +82,9 @@ Run the variant loop for <TypeName>:
    - 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": [...] }
+   generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
+   Use the `mode` field to pick the subdir: component → components/, collection → collections/, external → externals/.
+   Format: { "typeName": "<TypeName>", "mode": "<mode>", "variants": [...] }
 
 5. COMMIT: git add docs/cms-guidelines/screenshots/ generated/cms-discovery/
            git commit -m "chore(bl): variant screenshots for <TypeName>"
@@ -122,7 +125,7 @@ Example for Hero:
 node scripts/guidelines/capture-screenshots.mjs --variants /tmp/hero-variants.json
 ```
 
-Saves to `docs/cms-guidelines/screenshots/hero-*.png`.
+Saves to `docs/cms-guidelines/screenshots/components/hero-*.png` (or `collections/` for collection types).
 
 ### 3 — Evaluate
 
@@ -134,8 +137,10 @@ If not suitably different: replace rejected screenshots with suggestions, re-cap
 ### 4 — Save accepted list
 
 ```bash
-mkdir -p generated/cms-discovery/accepted-variants
-# Write manually or via script
+# Use the appropriate subdir based on mode: components/, collections/, or externals/
+mkdir -p generated/cms-discovery/accepted-variants/components
+# Write manually or via script — e.g. for a component:
+# generated/cms-discovery/accepted-variants/components/hero.json
 ```
 
 ### 5 — Commit
@@ -157,13 +162,13 @@ git commit -m "chore(bl): variant screenshots for Hero"
     {
       "label": "default",
       "description": "All fields populated, no colour override.",
-      "screenshotPath": "docs/cms-guidelines/screenshots/hero-default.png",
-      "showcaseParams": {}
+    "screenshotPath": "docs/cms-guidelines/screenshots/components/hero-default.png",
+    "showcaseParams": {}
     },
     {
       "label": "navy",
       "description": "Navy background + Off White text.",
-      "screenshotPath": "docs/cms-guidelines/screenshots/hero-navy.png",
+      "screenshotPath": "docs/cms-guidelines/screenshots/components/hero-navy.png",
       "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
     }
   ]

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

@@ -14,8 +14,9 @@ variants (like flipped). The screenshots are then used to write the "What it loo
 - **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`).
+- **Palette:** colour names from `generated/cms-discovery/theme-context.md` (generated by
+  `cms-generate-collection-guidelines` from `tailwind.config.json`). This is the authoritative
+  source — use it in preference to `field-list.json` or `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).
@@ -35,12 +36,15 @@ should be able to tell them apart at a glance.
 Component source:
 <COMPONENT_SOURCE>
 
-Palette (backgroundColour options):
+Palette (from generated/cms-discovery/theme-context.md — use ONLY these names):
+Background colours (backgroundColour):
 <BACKGROUND_COLOURS>
 
-Text colour options (textColour):
+Text colours (textColour, i.e. foreground colours):
 <TEXT_COLOURS>
 
+Do NOT invent or paraphrase colour names. Use the exact names from theme-context.md.
+
 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).