@se-studio/project-build 1.0.125 → 1.0.126

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/project-build
 
+## 1.0.126
+
+### Patch Changes
+
+- Version bump: patch for changed packages
+
 ## 1.0.125
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/project-build",
-  "version": "1.0.125",
+  "version": "1.0.126",
   "description": "Build tools and management scripts for SE Studio projects",
   "repository": {
     "type": "git",
@@ -61,19 +61,19 @@
     "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
   },
   "dependencies": {
-    "@biomejs/biome": "^2.4.10",
+    "@biomejs/biome": "^2.4.12",
     "@biomejs/js-api": "^4.0.0",
-    "@biomejs/wasm-nodejs": "^2.4.10",
+    "@biomejs/wasm-nodejs": "^2.4.12",
     "change-case": "^5.4.4",
     "chroma-js": "^3.2.0",
-    "contentful-management": "^12.2.0",
-    "dotenv": "^17.4.0"
+    "contentful-management": "^12.3.1",
+    "dotenv": "^17.4.2"
   },
   "devDependencies": {
     "@types/chroma-js": "^3.1.2",
-    "@types/node": "^22.19.15",
+    "@types/node": "^22.19.17",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "node scripts/merge-contentful-skills.mjs && tsc --project tsconfig.build.json",

package/skills/contentful-cms/core/SKILL.md

@@ -235,11 +235,16 @@ cms-edit add CTA --target bottomContent
 # Add after a specific component
 cms-edit add HeroSimple --after @c1
 
-# Add inside a collection
+# Add inside a collection (--parent derives target field from the parent's content type)
+# collection parent → uses 'contents'; page/article parent → uses 'content' by default
 cms-edit add Card --parent @c2
+cms-edit add Hero --parent @c0 --target content   # explicit target when parent is a page
 
 # Add an explicit collection type
 cms-edit add CardGrid --content-type collection
+
+# Link an EXISTING entry instead of creating a new one (e.g. a shared CTA used on every page)
+cms-edit add CTA --content-type component --existing-id 4xKj2abcDef
 ```
 
 Discover available types first:
@@ -303,6 +308,16 @@ cms-edit links remove @c5 1
 cms-edit links move @c5 2 0
 ```
 
+You can also bulk-replace the `links` array on a component using `set --links`:
+
+```bash
+# Replace the entire links array with specific IDs
+cms-edit set @c5 links linkId1,linkId2,linkId3 --links
+
+# Append a link entry ID to the existing array
+cms-edit set @c5 links linkId4 --links --append
+```
+
 ## Assets
 
 ```bash
@@ -331,7 +346,13 @@ cms-edit nav add --label "Docs" --href https://docs.example.com --after @c1
 
 ```bash
 # Create a new page (session opens on the new entry)
+# All flags after --title are optional
 cms-edit create page --slug /about-us --title "About Us" --description "Learn about our team"
+cms-edit create page --slug /about-us --title "About Us" \
+  --template-id <template-entry-id> \
+  --featured-image <asset-id> \
+  --indexed \
+  --cms-label "About Us (internal)"
 
 # Create a new article (requires articleType entry ID)
 cms-edit create article --slug /blog/my-post --title "My Post" --article-type-id 3abcDef456
@@ -588,18 +609,164 @@ echo '[...]' | cms-edit run             # Pipe from stdin
 cms-edit run --file ops.json --dry-run  # Validate without saving
 ```
 
-Supported ops: `open`, `set`, `rtf`, `rtf-replace`, `save`.
+Supported ops: `open`, `set`, `rtf`, `rtf-replace`, `save`, `add`, `links-add`.
 
-Example `ops.json`:
+| Op | args | opts |
+|----|------|------|
+| `open` | `["/slug"]` | — |
+| `set` | `[ref, field, value]` | — |
+| `rtf` | `[ref, field, markdown]` | — |
+| `rtf-replace` | `[ref, field]` | `{ find, replacePlain?, mode? }` |
+| `save` | — | — |
+| `add` | `[type, contentType]` | `{ after?, parent?, target?, existingId? }` |
+| `links-add` | `[ref]` | `{ type, label, href?, slug?, id?, assetId? }` |
+
+The `add` op returns the new `@ref` in the step message; subsequent ops can reference it.
+
+Example `ops.json` — update an existing page with a new CTA that has two buttons:
 ```json
 [
   { "cmd": "open", "args": ["/pricing"] },
-  { "cmd": "set", "args": ["@c0", "heading", "New Heading"] },
-  { "cmd": "rtf", "args": ["@c1", "body", "## Section\n\nContent here."] },
+  { "cmd": "add", "args": ["CTA", "component"], "opts": { "target": "bottomContent" } },
+  { "cmd": "set", "args": ["@c5", "heading", "Ready to get started?"] },
+  { "cmd": "links-add", "args": ["@c5"], "opts": { "type": "external", "label": "Start free trial", "href": "https://app.example.com" } },
+  { "cmd": "links-add", "args": ["@c5"], "opts": { "type": "internal", "label": "Learn more", "slug": "/about" } },
   { "cmd": "save" }
 ]
 ```
 
+## Create Page or Article from JSON
+
+Create a complete page or article — including all components, fields, and CTA links — from a single declarative JSON file. This is the recommended approach for creating multiple pages or articles in bulk.
+
+```bash
+cms-edit create from-json --file page.json            # Create from file
+cms-edit create from-json --file page.json --dry-run  # Preview without writing
+cat page.json | cms-edit create from-json             # Pipe from stdin
+```
+
+**Page JSON schema:**
+
+```json
+{
+  "type": "page",
+  "slug": "/parent-coaching/digital-life-safety/cyberbullying",
+  "title": "Cyberbullying",
+  "description": "Optional meta description (SEO)",
+  "templateId": "contentful-template-entry-id",
+  "indexed": true,
+  "components": [
+    {
+      "contentType": "component",
+      "type": "HeroSimple",
+      "target": "content",
+      "fields": {
+        "heading": "Protecting Your Child from Cyberbullying",
+        "body": "## Why it matters\n\nContent here with **bold** and [links](https://example.com).",
+        "backgroundColour": "Yellow"
+      },
+      "links": [
+        { "type": "external", "label": "Download Guide", "href": "https://example.com/guide.pdf" },
+        { "type": "internal", "label": "Learn More", "slug": "/resources" }
+      ]
+    },
+    {
+      "contentType": "collection",
+      "type": "CardGrid",
+      "fields": { "heading": "Related topics" },
+      "items": [
+        {
+          "contentType": "component",
+          "type": "Card",
+          "fields": { "heading": "Screen Time" }
+        },
+        {
+          "existingId": "abc123def456",
+          "comment": "Reuse existing 'Emotional Regulation' card"
+        }
+      ]
+    },
+    {
+      "existingId": "xyz789ghi012",
+      "comment": "Shared 'Join BLK Now' CTA reused on every page"
+    }
+  ]
+}
+```
+
+**Article JSON schema:**
+
+```json
+{
+  "type": "article",
+  "slug": "/resources/publications/cyberbullying/new-research-2025",
+  "title": "New Research on Cyberbullying 2025",
+  "description": "Key findings from the 2025 cyberbullying study.",
+  "articleTypeId": "3abcDef456ghi",
+  "date": "2025-04-14",
+  "components": [
+    {
+      "contentType": "component",
+      "type": "RichText",
+      "fields": {
+        "body": "## Introduction\n\nNew research shows..."
+      }
+    },
+    {
+      "contentType": "component",
+      "type": "CTA",
+      "target": "bottomContent",
+      "links": [
+        { "type": "external", "label": "Download Full Report", "href": "https://example.com/report.pdf" }
+      ]
+    }
+  ]
+}
+```
+
+- `type` defaults to `"page"`. Set `"type": "article"` (or include `articleTypeId`) for articles.
+- `articleTypeId` is required for articles. Find valid IDs with `cms-edit list --type articleType`.
+- `date` defaults to today (YYYY-MM-DD) if omitted.
+
+**Key points:**
+- Any component entry in `components` or `items` may use `{ existingId }` to link an existing entry instead of creating a new one.
+- The same applies to `links` entries — use `{ existingId }` to attach an existing link entry.
+- `fields.body` (and any value containing newlines or Markdown syntax) is automatically converted to Contentful rich text.
+- `target` sets which content array to use: `topContent`, `content` (default), or `bottomContent`.
+- All entries are created as **drafts**. A human must publish in Contentful.
+- `--dry-run` prints the full plan without writing anything.
+
+## Find Existing Entries (for existingId)
+
+When building page JSON that references existing entries, find their Contentful IDs first:
+
+```bash
+# Search for a shared component by name
+cms-edit search "join blk now" --type component --json
+# → output includes "id" field — use this as existingId in your page JSON
+
+# Browse all components of a specific type
+cms-edit list --type component --filter 'fields.componentType=CTA'
+
+# Confirm an entry before referencing it
+cms-edit resolve 4xKj2abcDef
+```
+
+## Inventory & Status
+
+Use `sitemap` to see all pages in a space with their publication status:
+
+```bash
+cms-edit sitemap                              # All pages
+cms-edit sitemap --prefix /parent-coaching   # Filter by slug prefix
+cms-edit sitemap --status draft              # Draft pages only
+cms-edit sitemap --sort updated              # Most recently updated first
+cms-edit sitemap --tree                      # Tree view
+cms-edit sitemap --include page,article      # Include articles
+```
+
+**Note on bulk publish:** The tool cannot publish entries — all saves create drafts only. This is intentional. Review and publish drafts from the Contentful web app.
+
 ## Concurrent Sessions
 
 Use `--session <name>` or `CONTENTFUL_CMS_SESSION=<name>` to isolate parallel workflows.

package/skills/contentful-cms/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/contentful-cms/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"
 }