@se-studio/contentful-cms 1.0.11 → 1.0.13

package/CHANGELOG.md

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

package/README.md

@@ -251,7 +251,7 @@ Capture a PNG of a component, collection, external component, person, or page. *
 
 | Target | Command |
 |--------|---------|
-| Session ref (full-fidelity) | `cms-edit screenshot @c0` — all types (component, collection, externalComponent, person) via convert API and `/cms-preview/render-json` |
+| Session ref (full-fidelity) | `cms-edit screenshot @c0` — all types (component, collection, externalComponent, person) via convert API and `/cms/preview/render-json` |
 | JSON file (no Contentful) | `cms-edit screenshot --json-file path/to/entry.json` — IBase* JSON; validates or screenshots without a session |
 | By type (mock, no session) | `cms-edit screenshot --component HeroSimple`, `cms-edit screenshot --collection CardGrid` |
 | Page | `cms-edit screenshot` (current page) or `cms-edit screenshot /pricing` |

package/dist/commands/screenshot.js

@@ -14,9 +14,9 @@ const DEFAULT_VIEWPORT_WIDTH = 1280;
 const DEFAULT_VIEWPORT_HEIGHT = 900;
 const DEFAULT_BASE_URL = 'http://localhost:3000';
 function isComponentOrCollectionUrl(url) {
-    return (url.includes('/cms-showcase/render') ||
-        url.includes('/cms-preview/render') ||
-        url.includes('/cms-preview/render-json'));
+    return (url.includes('/cms/showcase/render') ||
+        url.includes('/cms/preview/render') ||
+        url.includes('/cms/preview/render-json'));
 }
 /** Collect repeatable --param key=value into an array. */
 function collectParam(value, prev) {
@@ -50,7 +50,7 @@ export function registerScreenshotCommand(program) {
         '    --collection CardGrid')
         .option('--component <type>', 'Showcase a component by type name (no session needed)')
         .option('--collection <type>', 'Showcase a collection by type name (no session needed)')
-        .option('--live', 'Fetch real Contentful data via /cms-preview/render?id=... (requires preview token)')
+        .option('--live', 'Fetch real Contentful data via /cms/preview/render?id=... (requires preview token)')
         .option('--out <path>', 'Output file path (default: ./screenshot-<type>-<timestamp>.png)')
         .option('--full', 'Capture the full scrollable page (passed to agent-browser)')
         .option('--embedded', 'Append &embedded=true to showcase URL (suppresses IframeHeightReporter)')
@@ -81,7 +81,7 @@ export function registerScreenshotCommand(program) {
                 const raw = fs.readFileSync(opts.jsonFile, 'utf-8');
                 const data = JSON.parse(raw);
                 const encoded = Buffer.from(raw, 'utf-8').toString('base64');
-                url = appendRequestParams(`${baseUrl}/cms-preview/render-json?data=${encoded}`, requestParams);
+                url = appendRequestParams(`${baseUrl}/cms/preview/render-json?data=${encoded}`, requestParams);
                 displayType = data?.type ?? 'json';
             }
             else if (opts.component || opts.collection) {
@@ -111,7 +111,7 @@ export function registerScreenshotCommand(program) {
                     throw new Error('Convert API returned no data.');
                 }
                 const encoded = Buffer.from(JSON.stringify(data), 'utf-8').toString('base64');
-                url = appendRequestParams(`${baseUrl}/cms-preview/render-json?data=${encoded}`, requestParams);
+                url = appendRequestParams(`${baseUrl}/cms/preview/render-json?data=${encoded}`, requestParams);
                 displayType = data?.type ?? entryId;
             }
             else if (target?.startsWith('/') || target?.startsWith('http')) {
@@ -254,7 +254,7 @@ function buildShowcaseUrl(baseUrl, type, mode, fields, embedded, clean, requestP
             params.set(key, value);
         }
     }
-    return `${baseUrl}/cms-showcase/render?${params.toString()}`;
+    return `${baseUrl}/cms/showcase/render?${params.toString()}`;
 }
 /** Appends requestParams as query parameters to an arbitrary URL. */
 function appendRequestParams(url, requestParams) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/contentful-cms",
-  "version": "1.0.11",
+  "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

@@ -17,7 +17,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    ```bash
    pnpm --filter <appName> generate-showcase
    ```
-   This writes `src/cms-showcase/showcase-examples.json`.
+   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
@@ -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).

package/skills/core/SKILL.md

@@ -422,7 +422,7 @@ If omitted, defaults to `http://localhost:3000` with a warning.
 
 ### From session ref (full-fidelity)
 
-`cms-edit screenshot @c0` uses the app's convert API and `/cms-preview/render-json` so **all** entry types render with real converted data: component, collection, externalComponent, person. No separate "mock vs live" for refs.
+`cms-edit screenshot @c0` uses the app's convert API and `/cms/preview/render-json` so **all** entry types render with real converted data: component, collection, externalComponent, person. No separate "mock vs live" for refs.
 
 ```bash
 # Any entry type (component, collection, externalComponent, person)
@@ -445,7 +445,7 @@ cms-edit screenshot --json-file path/to/component.json
 
 ### By type (showcase mock, no session)
 
-Uses `/cms-showcase/render` with mock data. Fast, no preview token.
+Uses `/cms/showcase/render` with mock data. Fast, no preview token.
 
 ```bash
 cms-edit screenshot --component HeroSimple
@@ -469,7 +469,7 @@ cms-edit screenshot /about-us --full
 | Flag | Description |
 |------|-------------|
 | `--json-file <path>` | Read IBase* JSON from file and screenshot via render-json (no Contentful) |
-| `--live` | Legacy: use `/cms-preview/render?id=...` for ref (optional; @ref is already full-fidelity) |
+| `--live` | Legacy: use `/cms/preview/render?id=...` for ref (optional; @ref is already full-fidelity) |
 | `--out <path>` | Output file path (default: `./screenshot-<type>-<timestamp>.png`) |
 | `--full` | Full-page capture (passed to `agent-browser screenshot --full`) |
 | `--embedded` | Append `&embedded=true` to showcase URL (suppresses IframeHeightReporter) |

package/skills/screenshots/SKILL.md

@@ -10,9 +10,9 @@ Use this skill when capturing **screenshots** of components, collections, pages,
 
 ## Commands
 
-- **From session ref** (full-fidelity): `cms-edit screenshot @c0` — uses the convert API and `/cms-preview/render-json` so **all** entry types render with real data: component, collection, externalComponent, person. Add `--full` for full-page capture (auto-applied for component/collection).
-- **From JSON file** (no Contentful): `cms-edit screenshot --json-file path/to/entry.json` — reads an IBase* JSON (e.g. from `read @c0 --json` or an export), base64-encodes it, and opens `/cms-preview/render-json?data=...`. Use to validate or screenshot without a session or preview token.
-- **By type** (no session, mock): `cms-edit screenshot --component HeroSimple`, `cms-edit screenshot --collection CardGrid` — uses `/cms-showcase/render` with mock data.
+- **From session ref** (full-fidelity): `cms-edit screenshot @c0` — uses the convert API and `/cms/preview/render-json` so **all** entry types render with real data: component, collection, externalComponent, person. Add `--full` for full-page capture (auto-applied for component/collection).
+- **From JSON file** (no Contentful): `cms-edit screenshot --json-file path/to/entry.json` — reads an IBase* JSON (e.g. from `read @c0 --json` or an export), base64-encodes it, and opens `/cms/preview/render-json?data=...`. Use to validate or screenshot without a session or preview token.
+- **By type** (no session, mock): `cms-edit screenshot --component HeroSimple`, `cms-edit screenshot --collection CardGrid` — uses `/cms/showcase/render` with mock data.
 - **Page**: `cms-edit screenshot` (current open page) or `cms-edit screenshot /resources/publications/other/my-slug`
 - **URL only** (no agent-browser needed): `cms-edit screenshot @c0 --url-only`
 
@@ -29,8 +29,8 @@ Check the site's URL structure (e.g. `/resources/publications/<type>/<slug>`) an
 
 When using `--component <type>` or `--collection <type>` (no session), the default is **mock** (showcase). Use `--live` with a ref to prefer the legacy direct preview URL; for `@ref`, full-fidelity is already the default via convert → render-json.
 
-- **Mock:** `/cms-showcase/render` with mock data; fast, no preview token.
-- **Live** (with ref): `cms-edit screenshot @c0 --live` — uses `/cms-preview/render?id=...`; equivalent for component/collection/externalComponent to the default @ref path.
+- **Mock:** `/cms/showcase/render` with mock data; fast, no preview token.
+- **Live** (with ref): `cms-edit screenshot @c0 --live` — uses `/cms/preview/render?id=...`; equivalent for component/collection/externalComponent to the default @ref path.
 
 ## Checking your work