@se-studio/contentful-cms 1.0.36 → 1.0.38

package/skills/image-guide/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: "Image Guide"
+description: "Generate a comprehensive image guide (both Markdown and HTML) for a site's CMS image assets, with rich AI-generated visual descriptions and content relationship trees."
+---
+
+# Skill: contentful-cms — Image Guide
+
+Use this skill to generate a **fully enriched image guide** for a site. The guide documents every image in the CMS with:
+- Rich visual descriptions generated by inspecting each image
+- Content relationship tree showing which pages/components use each image
+- Two output formats: Markdown (AI-consumable) and HTML (human reference)
+
+The output files are written to the app's `docs/` directory (or a path you specify).
+
+## When to use
+
+- Client or team wants a reference guide for all images in the CMS
+- Need to know where a specific image is used across the site
+- Preparing image guidance for AI agents that will be choosing images
+- Auditing image coverage or identifying unused assets
+
+## Prerequisites
+
+- `cms-edit` is configured for the target space (run `cms-edit health` to verify)
+- You have read access to the image URLs (standard Contentful CDN URLs work)
+- The app directory is known (e.g. `apps/example-brightlifekids/`)
+
+## Brand Context
+
+Before starting, check if a brand context skill is available (e.g., "BrightLife Kids Brand Context"). If so, incorporate brand terminology in the descriptions and "When to use" guidance.
+
+---
+
+## Workflow
+
+### Step 0 — Load description cache
+
+Each image's description is stored as its own small file to avoid token-limit issues when reading or writing:
+
+```
+docs/descriptions/{assetId}.json
+```
+
+**To check if an image is already cached:**
+```bash
+ls docs/descriptions/{assetId}.json 2>/dev/null && echo "cached" || echo "not cached"
+```
+
+**Per-image file format:**
+```json
+{
+  "subjects": "...",
+  "setting": "...",
+  "composition": "...",
+  "colours": "...",
+  "mood": "...",
+  "style": "...",
+  "constraints": "...",
+  "whenToUse": "...",
+  "inspectedAt": "2026-04-15T10:00:00Z"
+}
+```
+
+**Write-through caching — CRITICAL:** After visually inspecting each NEW image, immediately write its description to `docs/descriptions/{assetId}.json` using the Write tool BEFORE inspecting the next image. One image → one Write call → next image. Each file is tiny (~1KB), so no token limits apply.
+
+If `docs/descriptions/{assetId}.json` already exists, read it and use the cached data — **skip the vision call entirely**.
+
+At the end of the run, report: `N from cache, M newly inspected`.
+
+**Phase discipline — cache first, guides second:** Complete ALL image inspections and per-image cache writes before starting any guide file. Do not interleave inspection with guide writing.
+
+> **Note:** If a legacy `docs/image-descriptions-cache.json` file exists, ignore it. The per-file cache supersedes it.
+
+### Step 1 — Gather structural data
+
+Run the audit command to get all images and their page/component usages:
+
+```bash
+cms-edit --json audit images
+```
+
+This outputs JSON with every image asset including:
+- Asset ID, title, filename, dimensions, MIME type, CDN URL
+- `usages[]`: the slug-bearing ancestors (page, article, articleType, pageVariant, tag, person) that ultimately use this asset. Intermediate wrapper entries (media, visual, component, etc.) are walked through transparently and not included. Each usage has `{ id, contentType, label, slug }`.
+
+Save the output to a temporary file or keep it in context.
+
+If the output is large, focus on images grouped by page. Use `cms-edit audit tree --page /<slug>` to see the relationship tree for a specific page:
+
+```bash
+cms-edit audit tree --page /
+cms-edit audit tree --page /families
+```
+
+### Step 2 — Inspect each image visually
+
+For each image in the JSON output, fetch the image URL and inspect it carefully. The CDN URL supports resize parameters — use `?w=800&q=85` for a good preview:
+
+```
+https://images.ctfassets.net/{spaceId}/{assetId}/{hash}/{filename}?w=800&q=85
+```
+
+For each image generate a **visual description** covering ALL of these fields:
+
+| Field | What to capture |
+|-------|----------------|
+| **Subjects** | Count of people, apparent ages, genders (if relevant), expressions, what they are doing |
+| **Setting** | Indoor/outdoor, room type or environment, background detail level, time of day |
+| **Composition** | Landscape or portrait, crop tightness (headshot / mid-shot / wide / full-bleed), focal point position, negative space |
+| **Colours** | 3–5 dominant colours with approximate descriptions (e.g. "warm cream, sage green, muted terracotta"), warm vs cool tone, contrast level |
+| **Mood** | One or two words: playful, warm, clinical, energetic, calm, aspirational, inclusive, serious |
+| **Style** | Photography (stock / custom-produced), illustration, icon, UI mockup, logo |
+| **Constraints** | What the image does NOT have — e.g. "no text overlay space", "subject fills frame", "no negative space for overlay", "transparent background" |
+
+For icons, logos, and UI mockups, the description can be shorter and focus on what the graphic represents and its visual style.
+
+### Step 3 — Determine "When to use" guidance
+
+Based on the image's current usages and its visual content, write a concise "When to use" paragraph covering:
+- Component types it suits (Hero, CtaCard, wide-format, etc.)
+- Content topics or page contexts where it fits
+- What NOT to use it for (age group constraints, format constraints, etc.)
+- Any reuse notes (e.g. "also used as /partners hero — suitable for both card and full-width formats")
+
+### Step 4 — Write the Markdown guide
+
+Output path: `docs/image-guide.md` inside the app directory (e.g. `apps/example-brightlifekids/docs/image-guide.md`).
+
+**IMPORTANT — chunked writing to avoid output token limits:** The guide file will be large (many KB). Never try to write the entire file in a single Write tool call. Instead, use bash heredoc append operations in batches:
+
+```bash
+# First call — write file header + first ~35 images (use actual app path)
+cat > apps/example-brightlifekids/docs/image-guide.md << 'MDEOF'
+# BrightLife Kids — Image Guide
+
+> Generated 2026-04-15. Space: blk. 202 images documented.
+...
+## Image 1 · filename.jpg
+...
+MDEOF
+
+# Subsequent calls — APPEND next batch (note >>)
+cat >> apps/example-brightlifekids/docs/image-guide.md << 'MDEOF'
+## Image 36 · filename.jpg
+...
+MDEOF
+```
+
+Keep each bash call to **35 images maximum** (~18,000 tokens of content per call). Use as many `cat >>` append calls as needed. For descriptions, read from the cached `docs/descriptions/{assetId}.json` files rather than re-inspecting.
+
+Use this structure:
+
+```markdown
+# {Brand} — Image Guide
+
+> Generated {date}. Space: {spaceKey}. {N} images documented.
+>
+> **AI usage note**: Each entry below has consistent fields for programmatic selection.
+> Match `Subjects`, `Setting`, and `Mood` to the content context. Use `Constraints` to
+> rule out images that won't work for a given layout. `Used on` shows exact page/component context.
+
+---
+
+## {image title} · {filename}
+
+**Asset ID**: `{id}`  
+**Dimensions**: {width}×{height} · {contentType}  
+**CDN URL**: `{url}?w=800&q=85`
+
+**Used on**:
+- {slug} — {contentType} "{label}"
+- _(repeat for each usage; omit if usages array is empty — mark as "Unused / unattached")_
+
+**Subjects**: {description}  
+**Setting**: {description}  
+**Composition**: {description}  
+**Colours**: {description}  
+**Mood**: {description}  
+**Style**: {description}  
+**Constraints**: {description}
+
+**When to use**: {paragraph}
+
+---
+```
+
+Repeat for every image. Group images by page/section using `## Section: {page title}` headings before each page's images, matching the structure the `audit images` output provides.
+
+### Step 5 — Write the HTML guide
+
+Output path: `docs/image-guide.html` inside the app directory.
+
+**IMPORTANT — chunked writing:** HTML files are much larger than Markdown. Use the same bash heredoc append strategy, but with **smaller batches of 15–20 image cards** per operation. Start with the full `<html>`, `<head>`, CSS, and opening body tags, then append cards in batches, then append the closing tags last.
+
+The HTML guide is a self-contained human reference (no server needed). Model it on the existing `tmp/blk-image-guide.html` style but with the following enhancements:
+
+1. **Visual detail block**: Add a new `<div class="visual-detail-box">` section in each card containing the structured visual fields (Subjects, Setting, Composition, Colours, Mood, Style, Constraints) as a compact `<table>`.
+
+2. **Usage tree**: In the metadata table, expand the `Pages` row to show the full chain: `{pageSlug} → {componentType} "{label}" (field: {fieldName})`.
+
+3. **Site tree section**: Add a collapsible `<details>` section at the top of the page titled "Full Site Content Tree" that shows the inverse view — for each page, what images appear on it.
+
+4. **LLM note**: Update the LLM usage note at the top to reference the structured visual fields.
+
+The HTML must:
+- Be fully self-contained (inline CSS, no external dependencies)
+- Work without a web server (file:// protocol)
+- Match the brand colours of the target site
+- Show thumbnail images with lazy loading
+
+### Step 6 — Verify and report
+
+After writing both files, confirm:
+1. Every image from the `audit images` output has an entry in both files
+2. The "Used on" relationships match what `audit tree` shows
+3. The Markdown file is clean and can be read without a browser
+
+Present a summary:
+
+| Image | Pages used on | Visual description added | Notes |
+|-------|--------------|--------------------------|-------|
+| ...   | ...           | ✓                        | ...   |
+
+Report the output paths and any images that had no usages (potential orphans).
+
+---
+
+## Tips
+
+- **Efficient image inspection**: Fetch images in batches. Process all images for a page together before moving to the next page.
+- **Orphaned assets**: Images with no usages (`usages: []` in the JSON) are likely unused. Flag them but still document them — they may be intentionally held in reserve.
+- **SVG icons**: For SVG assets, use the direct URL (no resize params needed). Describe the graphic shape and colour precisely.
+- **Stock vs custom**: Check the filename for patterns like `AdobeStock_`, `pexels-`, `unsplash-` to identify stock images. Custom-produced images typically have branded filenames.
+- **Mobile variants**: Some components have both `visual` and `mobileVisual` fields. If the same image appears in both, note the dual-use in the description.
+
+## Related skills
+
+- **core**: Full cms-edit workflow reference
+- **alt-text-audit**: Audit and improve alt text on existing images
+- **contentful-cms-screenshots**: Take live screenshots of pages for reference

package/skills/manifest.json

@@ -5,6 +5,7 @@
   "rich-text": "Rich text (rtf) and embeds (append/insert); Markdown support",
   "screenshots": "Screenshot command, agent-browser requirement, mock vs live, --url-only",
   "alt-text-audit": "Audit and improve image alt text across site pages",
+  "image-guide": "Generate a comprehensive image guide (MD + HTML) with AI visual descriptions and content relationship trees",
   "seo-descriptions": "Generate or improve SEO meta descriptions for pages",
   "schema-org": "Generate Schema.org structured data as Mustache templates"
 }