@se-studio/skills 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @se-studio/skills
 
+## 1.5.1
+
+### Patch Changes
+
+- aa6f11b: Breaking cms-edit CLI prune (2.6.0):
+
+  **Removed**
+
+  - `ensure` — use `create … --if-not-exists`
+  - `skill` command (including `skill install`) — use `npx skills add @se-studio/skills`
+  - `contentful-cms` bin alias — use `cms-edit` only
+  - top-level `audit` (`images`, `tree`) — use `asset review --include-usage` and `list`/`open`/`peek`
+  - `backup`, `restore`, `revert` — use `diff` + `discard` + Contentful UI
+  - top-level `run` — use `batch run --file`
+  - top-level `colours`, `types` — use `schema colours`, `schema types <content-type>`
+  - `contentful-cms-image-guide` skill — merged into `contentful-cms-media-review`
+
+  **Added**
+
+  - `create from-json --if-not-exists`
+  - `asset review --include-usage` (slug-bearing usage ancestry)
+  - `batch run` subcommand
+
+  **Migration**
+
+  | Old                                      | New                                            |
+  | ---------------------------------------- | ---------------------------------------------- |
+  | `cms-edit ensure tag-type …`             | `cms-edit create tag-type … --if-not-exists`   |
+  | `cms-edit run --file x.json`             | `cms-edit batch run --file x.json`             |
+  | `cms-edit colours`                       | `cms-edit schema colours`                      |
+  | `cms-edit types component`               | `cms-edit schema types component`              |
+  | `cms-edit audit images`                  | `cms-edit --json asset review --include-usage` |
+  | `cms-edit backup` / `restore` / `revert` | `diff` + `discard`; Contentful UI              |
+  | `cms-edit skill install`                 | `npx skills add @se-studio/skills`             |
+
+- db737d9: Add `site-workflows-deps-update` skill for updating dependencies across se-core-product and consumer repos with Next 15 / Node 24 pins, unified no-pnpm-patches enforcement, and pnpm 11.x updates.
+- 1262175: Remove `cms-edit sitemap` command. Use `list --type <type>` for content discovery. Update skills, MCP prompts, and editor task playbooks.
+
 ## 1.5.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",

package/references/deps-update/projects.registry.json

@@ -0,0 +1,67 @@
+{
+  "canonicalPatchesScript": "~/source/se/se-core-product/scripts/check-no-pnpm-patches.mjs",
+  "pinOverrides": {
+    "next": "^15.5.19",
+    "@types/node": "^24.13.2"
+  },
+  "pnpm": {
+    "major": 11,
+    "engines": "11.x"
+  },
+  "projects": [
+    {
+      "key": "se-core-product",
+      "displayName": "SE Core Product",
+      "path": "~/source/se/se-core-product",
+      "branch": "dev",
+      "validate": "bash scripts/check-circular-imports.sh && pnpm skills:validate && pnpm format; pnpm type-check",
+      "workspace": true,
+      "hasPinOverrides": true
+    },
+    {
+      "key": "se2026",
+      "displayName": "SE Studio Site",
+      "path": "~/source/se/se-website-2026",
+      "branch": "develop",
+      "validate": "pnpm check && pnpm type-check",
+      "workspace": true,
+      "hasPinOverrides": false
+    },
+    {
+      "key": "brightline",
+      "displayName": "Brightline Sites",
+      "path": "~/source/customers/brightline/brightline-sites",
+      "branch": "develop",
+      "validate": "pnpm -r validate",
+      "workspace": true,
+      "hasPinOverrides": false
+    },
+    {
+      "key": "om1",
+      "displayName": "OM1 Website",
+      "path": "~/source/customers/om1/om1-website",
+      "branch": "develop",
+      "validate": "pnpm check && pnpm type-check && pnpm validate:routes",
+      "workspace": true,
+      "hasPinOverrides": false
+    },
+    {
+      "key": "pointme",
+      "displayName": "PointMe Marketing Site",
+      "path": "~/source/customers/pointme/develop-marketing-site",
+      "branch": "develop",
+      "validate": "pnpm check && pnpm type-check",
+      "workspace": true,
+      "hasPinOverrides": false
+    },
+    {
+      "key": "pedestal",
+      "displayName": "Pedestal Sites",
+      "path": "~/source/customers/pedestal/pedestal-sites",
+      "branch": "develop",
+      "validate": "pnpm -r validate",
+      "workspace": true,
+      "hasPinOverrides": false
+    }
+  ]
+}

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

@@ -15,7 +15,7 @@ If no brand context is available, ask the user about any brand-specific terms be
 
 ## Workflow
 
-1. **Get all pages**: `cms-edit sitemap`
+1. **Get all pages**: `cms-edit list --type page`
 2. **For each page** (or a specific page if the user specified one):
    a. `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
    b. `cms-edit snapshot` — identify components with visual/image/media fields

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

@@ -279,8 +279,8 @@ cms-edit add CTA --content-type component --existing-id 4xKj2abcDef
 
 Discover available types first:
 ```bash
-cms-edit types component
-cms-edit types collection
+cms-edit schema types component
+cms-edit schema types collection
 ```
 
 ### Remove a component
@@ -436,9 +436,9 @@ cms-edit create tag --json-file tag.json --tag-type presentation-type --if-not-e
 cms-edit create taxonomy-from-json --file taxonomy.json --if-not-exists
 
 # Idempotent single-entry creates
-cms-edit ensure tag-type --slug conference-venue --name "Conference Venue"
-cms-edit ensure tag --slug asco-2025 --name "ASCO 2025" --tag-type conference-venue \
-  --description "Annual ASCO conference." --featured-image <logoAssetId>
+cms-edit create tag-type --slug conference-venue --name "Conference Venue" --if-not-exists
+cms-edit create tag --slug asco-2025 --name "ASCO 2025" --tag-type conference-venue \
+  --description "Annual ASCO conference." --featured-image <logoAssetId> --if-not-exists
 ```
 
 See `cms-edit help fields-taxonomy` and `cms-edit help taxonomy-from-json` for field reference and batch schema.
@@ -463,7 +463,7 @@ cms-edit read @c0 bio
 
 **Site/runtime:** Resolved **person links** (`IPersonLink` from the REST API — article authors, collection contents, `contentfulAllPersonLinks`, related-people helpers) include **`bio`** when set in CMS. Use for team cards, related-people collections, and markdown/search export — not only full person detail pages.
 
-**Idempotent taxonomy:** `--if-not-exists` / `ensure` are check-then-create — safe for sequential imports, not for parallel creates on the same slug.
+**Idempotent taxonomy:** `--if-not-exists` is check-then-create — safe for sequential imports, not for parallel creates on the same slug.
 
 ```bash
 # Resolve taxonomy IDs without a session
@@ -481,8 +481,8 @@ cms-edit search "pricing page"
 cms-edit search "hero" --type component
 
 # List valid type values
-cms-edit types component
-cms-edit types collection
+cms-edit schema types component
+cms-edit schema types collection
 
 # List entries with filters
 cms-edit list --type article --sort date -n 10     # recent articles by publication date
@@ -491,7 +491,7 @@ cms-edit list --type article --slug my-article    # article with a specific slug
 cms-edit list --type article --has-field tags      # articles where tags field is non-empty
 
 # Find draft articles, then peek/open (both support drafts via CMA)
-cms-edit sitemap --include article --status draft
+cms-edit list --type article --sort date
 cms-edit peek --article-slug resources/blog/my-post
 # Only list --published / resolve --published are published-only
 
@@ -566,7 +566,7 @@ cms-edit save
 ### Add a new section to a page
 ```bash
 cms-edit open --page-slug /products
-cms-edit types component  # discover what's available
+cms-edit schema types component  # discover what's available
 cms-edit add CTA --after @c3
 cms-edit set @c4 heading "Ready to get started?"
 cms-edit rtf @c4 body --markdown "Join thousands of teams who trust us."
@@ -611,17 +611,11 @@ cms-edit preview showcase --collection CardGrid --param backgroundColour=Navy
 
 For CMS guidelines batch PNG capture, use `cms-capture-screenshots` from `@se-studio/project-build` (separate from cms-edit; requires agent-browser).
 
-## Revert
+## Undo changes
 
-Field-level undo — restore fields to their original values from when the session was opened.
+There is no field-level revert command. To abandon unsaved edits: `cms-edit diff` to review, then `cms-edit discard` (or `discard --all`). To roll back saved drafts, use the Contentful web app version history.
 
-```bash
-cms-edit revert @c0 heading       # Revert a single field to its original value
-cms-edit revert @c0               # Revert all fields on an entry
-cms-edit revert --all             # Revert all modified entries (session stays open)
-```
-
-Note: Entries created via `add` cannot be reverted — use `remove` instead.
+Note: Entries created via `add` that you have not saved can be removed with `cms-edit remove <ref>`.
 
 ## Health Check
 
@@ -633,25 +627,27 @@ cms-edit health   # Check config file, space config, Contentful connectivity
 
 ## Schema Inspection
 
-Inspect field definitions for a content type. Prefer this over `cms-edit types <ct>` when you need full field info.
+Inspect field definitions for a content type. Use `cms-edit schema types <ct>` for type-discriminator values only.
 
 ```bash
 cms-edit schema component         # Show all fields, types, enum values, link targets
 cms-edit schema component --json  # Full JSON output
 ```
 
-## Sitemap
+## Content catalog (`list`)
 
-Browse all pages in the space.
+Browse entries by content type (index-backed for catalog types). Run `cms-edit index sync` once per space, or let commands auto-sync.
 
 ```bash
-cms-edit sitemap                         # All pages, sorted by slug
-cms-edit sitemap --prefix /blog          # Filter by slug prefix
-cms-edit sitemap --status draft          # Draft pages only
-cms-edit sitemap --sort updated          # Most recently updated first
-cms-edit sitemap --include article --sort date  # Articles by publication date
-cms-edit sitemap --tree                  # Tree rendering
-cms-edit sitemap --include page,article  # Include articles too
+cms-edit list --type page                         # All pages (label sort)
+cms-edit list --type page --sort updated          # Most recently updated first
+cms-edit list --type article --sort date          # Articles by publication date
+cms-edit list --type pageVariant                  # A/B or variant pages
+cms-edit list --type tag --tag-type-name "Topic"  # Tags under a tag type
+cms-edit list --type tagType                      # Tag types
+cms-edit list --type articleType                  # Article types
+cms-edit list --type navigation                   # Navigations
+cms-edit list --type person --force-cma           # People (not in catalog index)
 ```
 
 ## Peek
@@ -663,14 +659,14 @@ cms-edit peek --page-slug /pricing   # Show snapshot of /pricing; your active se
 cms-edit peek --id <entryId>         # Look up by entry ID
 ```
 
-## Batch Operations (run)
+## Batch Operations (batch run)
 
 Run a sequence of operations from a JSON file or stdin.
 
 ```bash
-cms-edit run --file ops.json            # Run batch ops from file
-echo '[...]' | cms-edit run             # Pipe from stdin
-cms-edit run --file ops.json --dry-run  # Validate without saving
+cms-edit batch run --file ops.json            # Run batch ops from file
+echo '[...]' | cms-edit batch run             # Pipe from stdin
+cms-edit batch run --file ops.json --dry-run  # Validate without saving
 ```
 
 Supported ops: `open`, `set`, `rtf`, `rtf-replace`, `save`, `add`, `links-add`.
@@ -823,15 +819,12 @@ cms-edit resolve 4xKj2abcDef
 
 ## Inventory & Status
 
-Use `sitemap` to see all pages in a space with their publication status:
+Use `list --type <type>` for inventory. Catalog types (page, article, pageVariant, template, taxonomy, navigation) use the local index. Use `--force-cma` for other types (person, customType, pageTest) or published-only with `--published`.
 
 ```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
+cms-edit list --type page
+cms-edit list --type article --sort date -n 20
+cms-edit index dump --reference-only          # Full catalog snapshot in terminal
 ```
 
 **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.

package/skills/contentful-cms-media-review/SKILL.md

@@ -115,9 +115,56 @@ Space key: `brightline` (space ID `96gdpqkm7elu`).
 
 Production page URLs and definitive unused-asset detection need CMA `links_to_asset` or a production crawl. When available, add columns `prodUrls` and `cmsUsages` to the spreadsheet.
 
+## Image guide (optional)
+
+Use this extension when the client wants a **reference guide** for all CMS images (Markdown + HTML), not just a quality spreadsheet.
+
+### Gather structural data
+
+```bash
+cms-edit index sync --space <space-key>
+cms-edit --json asset review --include-usage --include-passing --space <space-key> > /tmp/image-inventory.json
+```
+
+Each asset in JSON includes `usages[]`: slug-bearing ancestors (page, article, tag, person, etc.) that ultimately use the asset.
+
+To inspect how images relate to a specific page, use `cms-edit open --page-slug /<slug>` + `snapshot`, or `cms-edit peek --page-slug /<slug>` without affecting your session.
+
+### Description cache
+
+Store AI-generated visual descriptions per asset (avoids re-inspecting on reruns):
+
+```
+docs/descriptions/{assetId}.json
+```
+
+Per-image format:
+
+```json
+{
+  "subjects": "...",
+  "setting": "...",
+  "composition": "...",
+  "colours": "...",
+  "mood": "...",
+  "style": "...",
+  "constraints": "...",
+  "whenToUse": "...",
+  "inspectedAt": "2026-04-15T10:00:00Z"
+}
+```
+
+**Write-through caching:** After inspecting each new image, write `docs/descriptions/{assetId}.json` before moving to the next. Skip vision calls when the cache file exists.
+
+### Output files
+
+- `docs/image-guide.md` — AI-consumable Markdown (chunk writes: ~35 images per append)
+- `docs/image-guide.html` — self-contained human reference (chunk writes: ~15–20 cards per append)
+
+Use CDN URLs with `?w=800&q=85` for previews. Group entries by page using `usages[]` from the review JSON.
+
 ## Related
 
 - `contentful-cms-alt-text-audit` — per-page alt text fixes
-- `contentful-cms-image-guide` — full image inventory with AI descriptions
 - `cms-edit asset audit` — missing alt only (narrower, faster)
 - `cms-edit asset set-description <id> "alt"` — fix alt text on an asset

package/skills/contentful-cms-schema-org/SKILL.md

@@ -15,7 +15,7 @@ If no brand context is available, ask the user for these details.
 
 ## Phase 1: Analyse Site Structure
 
-1. `cms-edit sitemap` to get all pages and articles
+1. `cms-edit list --type page` and `cms-edit list --type article` for inventory
 2. For each page, use `fetch_page_markdown` (from site-workflows MCP server) to read content
 3. Categorise each page by Schema.org type:
 

package/skills/contentful-cms-seo-descriptions/SKILL.md

@@ -15,7 +15,7 @@ If no brand context is available, ask the user about their brand voice and targe
 
 ## Workflow
 
-1. **Get all pages**: `cms-edit sitemap`
+1. **Get all pages**: `cms-edit list --type page`
 2. **For each page** (or a specific page):
    a. **Read page content** using `fetch_page_markdown` (from the site-workflows MCP server) to understand what the page covers
    b. **Check current SEO**:

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

@@ -41,7 +41,7 @@ For engineering work in a site repo (Cursor, Grok, terminal):
 
 1. Configure `.contentful-cms.json` in the project (or `~/.contentful-cms.json`) with space credentials
 2. Run `npx skills add @se-studio/skills` or `pnpm skills:sync` in the monorepo
-3. Optionally `cms-edit skill install` for bundled cms-edit skills
+3. Bundled cms-edit skills (`core`, `setup`, etc.) are included when you run `npx skills add @se-studio/skills`
 4. Read `cms-edit/<site>/editor-pack/tasks-index.md` before editing content
 
 Do **not** register a local `mcpServers.cms-edit` entry in Claude Desktop — use the hosted connector URL instead.

package/skills/site-workflows-deps-update/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: site-workflows-deps-update
+description: "Update npm dependencies to latest across se-core-product and consumer SE Studio sites, one repo at a time. Pins Next.js 15 and Node 24, updates pnpm to latest 11.x, enforces no pnpm patches everywhere. Validates, commits, and pushes to dev/develop. Use when asked to update outdated packages or bump dependencies."
+---
+
+# SE dependency update (one project at a time)
+
+Update npm dependencies to **latest** in se-core-product and consumer repos that use `@se-studio/*` packages.
+
+**Registry:** [`packages/skills/references/deps-update/projects.registry.json`](../../references/deps-update/projects.registry.json) — paths, branches, validate commands.
+
+**Default:** Process **one repo per invocation**. At the end, summarize changes and offer the next project.
+
+**Never:** push to `main`/`master`; bump Next to 16; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`.
+
+---
+
+## Projects
+
+| key | displayName | branch |
+|-----|-------------|--------|
+| `se-core-product` | SE Core Product | `dev` |
+| `se2026` | SE Studio Site | `develop` |
+| `brightline` | Brightline Sites | `develop` |
+| `om1` | OM1 Website | `develop` |
+| `pointme` | PointMe Marketing Site | `develop` |
+| `pedestal` | Pedestal Sites | `develop` |
+
+User may name a key (`update deps in om1`) or ask to run through all projects sequentially.
+
+---
+
+## Step 1 — Preflight
+
+```bash
+node -v   # must be v24.x
+pnpm -v   # must be v11.x
+```
+
+In the target repo:
+
+1. Confirm the path from the registry exists; abort if missing.
+2. `git fetch origin && git checkout <branch> && git pull`
+3. Working tree must be clean (or user explicitly approves stash).
+4. Record `pnpm outdated -r` output for the commit summary.
+
+---
+
+## Step 2 — Bootstrap no-pnpm-patches check (all repos)
+
+Pedestal already ships `scripts/check-no-pnpm-patches.mjs`; other consumer repos may not. **Every project** must run this check — do not rely on only pedestal's custom validate script.
+
+If `scripts/check-no-pnpm-patches.mjs` is missing, copy the canonical script:
+
+```bash
+mkdir -p scripts
+cp ~/source/se/se-core-product/scripts/check-no-pnpm-patches.mjs scripts/check-no-pnpm-patches.mjs
+```
+
+Commit the bootstrap copy as part of the deps update commit when you add it.
+
+---
+
+## Step 3 — Pin overrides (before `--latest`)
+
+`pnpm update -r --latest` would bump `next` → 16 and `@types/node` → 26. Add or verify this block in `pnpm-workspace.yaml` (values from registry `pinOverrides`):
+
+```yaml
+overrides:
+  next: ^15.5.19
+  '@types/node': ^24.13.2
+```
+
+Skip if `hasPinOverrides` is already true and values match. Idempotent — merge into existing `pnpm-workspace.yaml` without removing other keys (`minimumReleaseAge`, `allowBuilds`, etc.).
+
+---
+
+## Step 4 — Update pnpm (all repos)
+
+Bump the package manager to the **latest pnpm 11.x** in root `package.json`:
+
+```bash
+LATEST_PNPM=$(npm view pnpm@11 version)
+# Set "packageManager": "pnpm@<LATEST_PNPM>" in package.json
+corepack use pnpm@${LATEST_PNPM}
+pnpm -v   # confirm matches packageManager
+```
+
+Keep `engines.pnpm` at `11.x` (do not jump to pnpm 12). If `engines.pnpm` is missing, add `"pnpm": "11.x"` alongside `"node": "24.x"`.
+
+---
+
+## Step 5 — Update dependencies
+
+```bash
+pnpm update -r --latest
+```
+
+If brightline or pedestal repos block fresh packages (`minimumReleaseAge: 1440`), retry with:
+
+```bash
+pnpm update -r --latest --no-minimum-release-age
+```
+
+Safety re-pin after update:
+
+```bash
+pnpm update -r next@^15 @types/node@^24
+pnpm install
+```
+
+Verify pins held:
+
+```bash
+pnpm outdated -r | rg '^(next|@types/node)' || true
+rg '"node"' package.json apps/*/package.json packages/*/package.json 2>/dev/null | rg -v '24' || true
+```
+
+`engines.node` must stay `24.x` or `>=24.0.0 <25` — revert any accidental bump to 25+.
+
+---
+
+## Step 6 — Validate (unified for all repos)
+
+Always run the patches check **once**, then the project validate from the registry:
+
+```bash
+node scripts/check-no-pnpm-patches.mjs && <validate from registry>
+```
+
+Registry `validate` commands intentionally **exclude** the patches check so every project uses the same enforcement. Do not skip this step for repos that lack it in their `package.json` scripts today.
+
+On failure: fix if trivial; otherwise `git checkout -- .` and stop **without** pushing.
+
+---
+
+## Step 7 — Commit and push
+
+```bash
+git add -A
+git commit -m "chore(deps): update dependencies (<displayName>)"
+git push origin <branch>
+```
+
+- se-core-product → `dev`
+- All consumer repos → `develop`
+- **Never** push to `main`/`master`
+
+---
+
+## Step 8 — Report
+
+Include in the summary:
+
+- Major dependency bumps (from the Step 1 audit diff)
+- pnpm version: before → after
+- Confirmed pins: Next 15.x, Node 24, `@types/node` ^24
+- Patches check bootstrapped (yes/no)
+- Remaining projects not yet updated
+
+Offer to continue with the next project.
+
+---
+
+## Optional: align `package.json` validate scripts
+
+After a successful update, you may add the patches check to the root `validate` script in consumer repos that lack it:
+
+```json
+"validate": "node scripts/check-no-pnpm-patches.mjs && pnpm check && pnpm type-check"
+```
+
+This is optional follow-up — the skill workflow always runs the check regardless.
+
+---
+
+## Troubleshooting
+
+| Issue | Action |
+|-------|--------|
+| `next` or `@types/node` still outdated to wrong major | Re-run overrides + safety re-pin; check `pnpm-workspace.yaml` overrides |
+| `corepack use` fails | Run `corepack enable` once, retry |
+| Validate fails after major bump | Check breaking-change release notes; fix or revert |
+| Repo path missing | Skip; note in report — see `docs/RELATED_PROJECTS.md` |
+| Patches check fails | Remove `patchedDependencies` / `patches/` — patches are forbidden in all SE repos |

package/skills/contentful-cms-image-guide/SKILL.md

@@ -1,239 +0,0 @@
----
-name: contentful-cms-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; use `preview url` / `preview showcase` for visual checks via browser MCP
-- **alt-text-audit**: Audit and improve alt text on existing images