@se-studio/contentful-cms 1.0.42 → 1.0.44

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/contentful-cms Changelog
 
+## 1.0.44
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
+## 1.0.43
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.42
 
 ### Patch Changes

package/package.json

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

package/skills/alt-text-audit/SKILL.md

@@ -1,60 +0,0 @@
----
-name: "Alt Text Audit"
-description: "Audit and improve image alt text across site pages using cms-edit, with brand-aware terminology and accessibility best practices."
----
-
-# Skill: contentful-cms — Alt Text Audit
-
-Use this skill when auditing or improving **image alt text** across a site's pages using `cms-edit`. Works with any brand context skill for customer-specific terminology.
-
-## Brand Context
-
-Before starting, check if a brand context skill is available (e.g., "OM1 Brand Context", "Something Else Brand Context"). If so, use its terminology, image interpretation guidelines, and brand voice when writing alt text.
-
-If no brand context is available, ask the user about any brand-specific terms before proceeding.
-
-## Workflow
-
-1. **Get all pages**: `cms-edit sitemap`
-2. **For each page** (or a specific page if the user specified one):
-   a. `cms-edit open /<slug>`
-   b. `cms-edit snapshot` — identify components with visual/image/media fields
-   c. For each image-bearing component:
-      - `cms-edit read @ref` to inspect fields
-      - Check `altText` on any image/visual references
-      - `cms-edit read @ref visual` to see asset details if needed
-   d. **Flag** images with:
-      - Missing alt text (empty or null)
-      - Generic alt text ("image", "photo", "banner", "screenshot", "img", "picture")
-      - Alt text that doesn't use brand terminology (if brand context available)
-      - Alt text over 125 characters
-   e. **Generate** improved alt text following the guidelines below
-   f. `cms-edit set @ref altText "new alt text"`
-   g. `cms-edit diff` to review, then `cms-edit save`
-
-## Alt Text Guidelines
-
-1. **Be specific and descriptive** — describe what is actually in the image
-2. **Use brand terminology** — refer to the brand context for correct terms
-3. **Keep under 125 characters** — screen readers truncate longer text
-4. **Don't start with** "Image of", "Photo of", "Picture of"
-5. **Decorative images** — set alt to "" (empty string) for dividers, background patterns
-6. **Context matters** — describe the image's purpose on the page, not just its visual content
-7. **Include relevant actions** — if people are doing something meaningful, describe it
-
-## Reading Page Content
-
-To understand a page before auditing its images, use `fetch_page_markdown` (from the site-workflows MCP server) with the page slug.
-
-## Output
-
-Present a summary table when complete:
-
-| Page | Component | Old Alt Text | New Alt Text | Status |
-|------|-----------|-------------|-------------|--------|
-
-Where Status is: Updated, Skipped (decorative), Already Good, or Needs Review.
-
-## Related skills
-
-See the **core** skill for the full cms-edit workflow (open, snapshot, read, set, save).

package/skills/cms-guidelines/README.md

@@ -1,166 +0,0 @@
-# CMS Guidelines Generation
-
-This directory contains the pipeline prompts and documentation for generating CMS component guideline fragments for any app in the monorepo.
-
----
-
-## What are CMS guidelines?
-
-Guidelines are short markdown fragments — one per CMS type — that describe how each component or collection looks, what fields it uses, how colours are applied, and how it behaves. They are merged into `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md`, a single document used to give LLMs accurate context about the app's component library.
-
----
-
-## Lifecycle: From content to guidelines
-
-1. **Build the site** — implement all components and collections; ensure all content is correct and published in Contentful.
-2. **Generate showcase data** — pull real Contentful data into the app's showcase:
-   ```bash
-   pnpm --filter <appName> generate-showcase
-   ```
-   This writes `src/generated/showcase-examples.json`.
-3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](.agents/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](.agents/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 [`.agents/skills/contentful-cms-generate-cms-guidelines/SKILL.md`](.agents/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-html-style-guide` | Generate `html-component-style-guide.md` from `tailwind.config.json` + `globals.css` |
-| `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` | 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/project-build`. Run `pnpm build` from the repo root to ensure they are built and linked.
-
----
-
-## `cms-generate-html-style-guide`
-
-Generates `docs/cms-guidelines/html-component-style-guide.md` — a design system reference for any LLM or developer authoring HTML in `HtmlComponent` CMS entries.
-
-Does not require a running dev server. Reads only local files:
-- `tailwind.config.json` → colour palette, typography classes, grid configuration
-- `src/app/globals.css` → custom utilities, RTF class names, CSS custom properties
-
-```bash
-# From the app directory:
-pnpm cms-generate-html-style-guide
-```
-
-The output file is a **static fragment** — not generated by the LLM component pipeline. It is automatically included as a preamble in `COMPONENT_GUIDELINES_FOR_LLM.md` when `cms-merge-guidelines` runs. Regenerate it whenever the design system changes.
-
----
-
-## `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/
-    html-component-style-guide.md     # design system reference (auto-generated; static fragment)
-    components/          # one .md per componentType
-    collections/         # one .md per collectionType
-    externals/           # one .md per externalComponentType
-    COMPONENT_GUIDELINES_FOR_LLM.md   # merged document (includes style guide as preamble)
-  generated/cms-discovery/
-    field-list.json
-    colour-hints.json
-    accepted-variants/
-      components/        # one .json per component type
-      collections/       # one .json per collection type
-      externals/         # one .json per external component type
-    screenshots/
-      components/        # PNG screenshots for components
-      collections/       # PNG screenshots for collections
-      externals/         # PNG screenshots for externals
-      index.json         # file field uses subpath e.g. "components/hero-default.png"
-```

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

@@ -1,77 +0,0 @@
-# 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

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

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

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