@se-studio/skills 1.4.3 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.4.4
+
+### Patch Changes
+
+- Add `cms-edit asset review` to audit visual assets (filename, alt text, dimensions, file size, GIF) from the Preview API index, plus the `contentful-cms-media-review` skill for spreadsheet workflows.
+
 ## 1.4.3
 
 ### Patch Changes

package/package.json

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

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

@@ -0,0 +1,123 @@
+---
+name: contentful-cms-media-review
+description: "Audit CMS images, videos, and Lottie animations for filename, alt text, dimensions, size, and GIF issues using cms-edit, then produce an Excel report of failures."
+---
+
+# Skill: contentful-cms — Media Review
+
+Use this skill to audit **visual assets** in a Contentful space and produce a spreadsheet of assets that fail quality checks.
+
+## When to use
+
+- Cleaning up CMS media before or after a migration
+- Finding oversized images, missing alt text, or animated GIFs
+- Brightline, SE Studio, or any site with `cms-edit` configured
+
+## Prerequisites
+
+- `cms-edit` configured for the target space (`cms-edit health`)
+- `CONTENTFUL_PREVIEW_ACCESS_TOKEN` set (default index uses Preview API / drafts)
+- Run `cms-edit index sync` before the review if the index is stale
+
+## Workflow
+
+### Step 1 — Sync the index
+
+```bash
+cms-edit index sync --space <space-key>
+```
+
+Use `--published` only when you want published/delivery content only.
+
+### Step 2 — Run the review
+
+```bash
+cms-edit --json asset review --space <space-key> > /tmp/media-review.json
+```
+
+Optional flags:
+
+| Flag | Purpose |
+|------|---------|
+| `--include-passing` | Include assets with no failures |
+| `--max-width 2000` | Max raster/video width (default 2000) |
+| `--max-image-kb 800` | Max image file size |
+| `--max-video-mb 8` | Max video file size |
+| `--max-lottie-kb 400` | Max Lottie JSON size |
+| `--published` | Use Delivery API index |
+
+Exit code **1** when any asset has failing issues (useful for CI).
+
+### Step 3 — Build the Excel report
+
+Create a workbook with **failures only** (default JSON output). Use the **xlsx** skill.
+
+**Sheet: Issues** — one row per failing asset
+
+| Column | Source field |
+|--------|----------------|
+| Asset ID | `assets[].id` |
+| Contentful URL | `assets[].contentfulUrl` |
+| CDN URL | `assets[].url` |
+| Title | `assets[].title` |
+| Filename | `assets[].fileName` |
+| Alt text | `assets[].description` |
+| Content type | `assets[].contentType` |
+| Width | `assets[].width` |
+| Height | `assets[].height` |
+| Size (KB) | `assets[].sizeKb` |
+| Media wrappers | `assets[].mediaEntryCount` |
+| Issue codes | `assets[].issues[].code` (comma-separated fails) |
+| Issue details | `assets[].issues[].message` (semicolon-separated) |
+| Updated | `assets[].updatedAt` |
+
+**Sheet: Summary**
+
+- `space`, `spaceId`, `environment`, `generated`, `preview`
+- `total`, `failingCount`, `warningCount`
+- `issueCounts` breakdown
+- Thresholds from `thresholds` object
+
+Default output path: `docs/media-review-<space>-<date>.xlsx` in the app directory.
+
+### Step 4 — Present findings
+
+Summarize for the user:
+
+- Total assets scanned vs failures
+- Top issue types (from `issueCounts`)
+- Quick wins (missing alt, animated GIFs, obvious stock filenames)
+- Note: `no_media_wrapper` is a **warning** — asset may still be used via rich text or be genuinely unused
+
+## What is checked
+
+| Check | Issue code | Severity |
+|-------|------------|----------|
+| Descriptive filename | `bad_filename` | fail |
+| Alt text present | `missing_alt` | fail |
+| Alt text quality | `weak_alt` | fail |
+| Width ≤ max (not SVG/Lottie) | `oversized_width` | fail |
+| File size limits | `oversized_file` | fail / warn |
+| Animated GIF | `animated_gif` | fail |
+| No media wrapper in index | `no_media_wrapper` | warn |
+
+## Brightline example
+
+```bash
+cd apps/brightline-website
+cms-edit index sync --space brightline
+cms-edit --json asset review --space brightline > /tmp/brightline-media-review.json
+```
+
+Space key: `brightline` (space ID `96gdpqkm7elu`).
+
+## Phase 2 (not yet in cms-edit)
+
+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.
+
+## 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/se-marketing-sites-smoke-test-setup/SKILL.md

@@ -29,6 +29,7 @@ Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smok
 | `pnpm smoke-test:cache` | `build` + `start` + double-pass `x-nextjs-cache` verify |
 | `pnpm smoke-test:deploy-check` | Post-build gate: `start` (no rebuild) + functional smoke — use in Vercel `buildCommand` |
 | `pnpm smoke-test:live` | Live deployment URL smoke — GitHub Action + Vercel Deployment Checks |
+| `pnpm revalidation-test` | `build` + `start` + revalidation matrix (warm → invalidate → cold → warm); see `revalidation.cases.json` and [CONTENTFUL_WEBHOOK_REVALIDATION.md](../../../../docs/CONTENTFUL_WEBHOOK_REVALIDATION.md) |
 
 Example `package.json` entries:
 
@@ -39,7 +40,8 @@ Example `package.json` entries:
 "smoke-test:audit": "SMOKE_TEST_AUDIT_CACHE_LOGS=true smoke-test-one 3012",
 "smoke-test:cache": "SMOKE_TEST_SERVER_SCRIPT=start SMOKE_TEST_VERIFY_CACHE=true smoke-test-one 3012",
 "smoke-test:deploy-check": "smoke-test-deploy-check",
-"smoke-test:live": "smoke-test-live"
+"smoke-test:live": "smoke-test-live",
+"revalidation-test": "node ../../scripts/revalidation-matrix-test.mjs 3012"
 ```
 
 **Vercel build gate** — append to root `vercel.json` so failed smoke fails the build before deploy:
@@ -161,8 +163,9 @@ Read (do not guess from constants alone):
 | `page` | Top-level CMS pages (not home, not article trees) | 2 |
 | `article-type-index` | e.g. `/work/`, `/blog/` | 1 |
 | `article` | Nested article/case-study URLs | 2 |
-| `tag` / `tags-index` | If in sitemap and enabled | 1–2 each |
-| `person` / `people-listing` | If in sitemap and enabled | 1–2 each |
+| `tag` / `tags-index` | If routes exist (sitemap optional) | 1–2 each |
+| `person` / `people-listing` | If routes exist (sitemap optional) | 1–2 each |
+| `not-found` | Non-existent path | 1 (`expectHtmlStatus: 404`) |
 
 **Exclude** obvious non-prod slugs: `tmp-*`, draft pages, unless intentionally tested.
 
@@ -187,11 +190,20 @@ curl -sI "http://localhost:<port>/some-path.md"
   "port": 3012,
   "cases": [
     { "category": "home", "label": "Home", "path": "/", "expectMarkdown": true },
-    { "category": "page", "label": "About", "path": "/about/", "expectMarkdown": true }
+    { "category": "page", "label": "About", "path": "/about/", "expectMarkdown": true },
+    {
+      "category": "not-found",
+      "label": "404 — unknown path",
+      "path": "/smoke-test-does-not-exist/",
+      "expectMarkdown": false,
+      "expectHtmlStatus": 404
+    }
   ]
 }
 ```
 
+`expectHtmlStatus` requires `@se-studio/site-check@^2.7.2`. Omit for normal 2xx HTML checks.
+
 Optional `cmsIntegrity` (local only — see section below):
 
 ```json