@se-studio/skills 1.4.2 → 1.4.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- Document SSG guardrails (Biome, route-build-policy, validate-build-routes) in se-marketing-sites-smoke-test-setup skill.
+
 ## 1.4.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.4.2",
+  "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
@@ -270,8 +282,67 @@ Remove legacy `smoke-test:validate-links`, `smoke-test-preload.cjs`, and bespoke
 3. Update `@se-studio/site-check` to `^2.6.1` when adopting integrity; otherwise `^2.1.2` minimum.
 4. Follow workflow above to create `smoke.cases.json`.
 
+## SSG guardrails (all marketing sites)
+
+Prevent `DYNAMIC_SERVER_USAGE` / production 500s on on-demand SSG routes (`●` in `next build`). Three layers — lint, build policy, production smoke.
+
+### 1. Biome — ban dynamic request APIs in SSG surfaces
+
+Copy the override block from `@se-studio/site-check/templates/biome-ssg-guardrails.override.json` into the app `biome.json` `overrides` array.
+
+Restricts request-time Next.js APIs in:
+
+- `src/app/layout.tsx`
+- `src/app/(cms-routes)/**`
+- `src/project/**`
+
+Banned: `next/headers` (headers, cookies, draftMode), `connection` from `next/server`, `unstable_noStore` from `next/cache`. `unstable_cache` and other `next/cache` exports remain allowed.
+
+Dynamic by design (no restriction): `(cms-dev)`, `preview`, `api`, `middleware.ts`.
+
+Lint is necessary but not sufficient — route policy + production smoke still required.
+
+Runs on every `pnpm check` / `pnpm validate`.
+
+### 2. Build route policy — no surprise `ƒ` on CMS segment routes
+
+Requires `@se-studio/site-check` **^2.7.0**.
+
+Commit `route-build-policy.json` beside `smoke.cases.json`. Start from `@se-studio/site-check/templates/route-build-policy.example.json` and adjust route segments to match the app.
+
+```json
+{
+  "allowedDynamic": ["/", "/articles", "/tags", "/people", "/_not-found"],
+  "mustBeSsgOrStatic": [
+    "/[level1]",
+    "/[level1]/[...slugs]",
+    "/articles/[articleType]",
+    "/articles/[articleType]/[...slugs]"
+  ]
+}
+```
+
+- `mustBeSsgOrStatic` — must be `●` or `○` in `next build`, never `ƒ`.
+- `allowedDynamic` — documents known `ƒ` routes; fail if a new `ƒ` appears without updating the policy.
+
+**Scripts:**
+
+```json
+"validate:routes": "validate-build-routes",
+"validate": "pnpm check && pnpm type-check && pnpm validate:routes"
+```
+
+`validate-build-routes` runs `pnpm build` and compares the Route (app) table to the policy. `smoke-test-one` also validates after build when `route-build-policy.json` exists (`SMOKE_TEST_VALIDATE_ROUTES=false` to skip).
+
+### 3. Production smoke (runtime safety net)
+
+`pnpm smoke-test:cache` / `smoke-test:deploy-check` catches breakage lint/policy miss. Keep mandatory in CI / Vercel build gates.
+
+**HubSpot bootstrap:** use `createHubSpotBootstrapScript()` with no args in root layout — not `headers()` + middleware pathname.
+
 ## Reference
 
 - HTTP + integrity example: `apps/example-empty/smoke.cases.json` and `scripts/smoke-test-run.ts` (monorepo).
-- Package API: `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `auditCacheLogs` from `@se-studio/site-check/smoke-test`.
+- SSG guardrails reference app: `apps/example-empty/route-build-policy.json` and `biome.json` overrides.
+- Package API: `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `auditCacheLogs`, `validateBuildRoutesFromBuildOutput` from `@se-studio/site-check/smoke-test`.
 - CMS integrity types: `@se-studio/site-check/cms-integrity`.

package/skills/vercel-logs-audit/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: vercel-logs-audit
+description: "Pull and triage Vercel error logs across SE Studio marketing sites (develop + production). Use when checking production errors, monitoring Vercel runtime issues, or running incremental log audits."
+---
+
+# Vercel logs audit
+
+Cross-project error monitoring for the 7 marketing sites in `docs/vercel-logs/projects.registry.json`.
+
+**Requires:** Vercel CLI (`vercel`), authenticated via `vercel login` or `VERCEL_TOKEN` in `.env.local`.
+
+**Output:** Generated under `docs/vercel-logs/` — **do not commit** except `projects.registry.json` and `README.md`.
+
+---
+
+## Quick start
+
+From repo root:
+
+```bash
+# Full pipeline: pull → filter → analyze
+pnpm vercel-logs
+
+# Subset
+pnpm vercel-logs --sites se2026,brightline --envs develop
+
+# Re-backfill 7 days (resets checkpoints for selected targets)
+pnpm vercel-logs --full
+
+# Plan fetches without calling Vercel
+pnpm vercel-logs:pull --dry-run
+```
+
+Individual steps:
+
+```bash
+pnpm vercel-logs:pull
+pnpm vercel-logs:filter
+pnpm vercel-logs:analyze
+```
+
+---
+
+## Incremental behaviour
+
+| Run | Window |
+|-----|--------|
+| First run (no `state.json`) | Last **7 days** per site × environment |
+| Subsequent runs | Since last checkpoint minus 5-minute overlap |
+| `--full` | Clears checkpoints and re-backfills 7 days |
+| `--since 2d` | Override start time for selected pull |
+
+Checkpoints live in `docs/vercel-logs/state.json` (gitignored).
+
+If a pull hits the Vercel log limit, the checkpoint is set to the **oldest fetched timestamp** (not `now`) so the next run can backfill older entries.
+
+---
+
+## Pipeline steps
+
+| Step | Input | Output |
+|------|-------|--------|
+| `pull` | Vercel CLI | `raw/<runId>/.../logs.jsonl` (raw JSON) |
+| `filter` | Raw JSONL + manifests | `errors/<runId>.jsonl` (normalized) |
+| `analyze` | Filtered JSONL | `reports/<runId>-summary.md` |
+
+---
+
+## Teams and projects
+
+The registry maps each site to a Vercel project and team scope:
+
+| Team | Sites |
+|------|-------|
+| `se-studio` | se2026, om1, pedestal, headwater |
+| `brightline` | brightline, brightlifekids |
+| `engineeringpointmes-projects` | pointme |
+
+Your Vercel account must have access to all three teams. Verify with `vercel whoami`.
+
+---
+
+## Reading results
+
+After `pnpm vercel-logs:analyze`, open:
+
+`docs/vercel-logs/reports/<runId>-summary.md`
+
+Triage in this order:
+
+1. **By site × environment** — which deploy surface is failing?
+2. **Top messages** — group identical errors (often one root cause)
+3. **Status codes** — 5xx vs application-level errors
+4. **Sample paths** — affected routes
+5. **Changes since previous run** — new regressions
+
+Filtered entries: `docs/vercel-logs/errors/<runId>.jsonl`
+
+Exit code **2** from analyze means errors were found (useful for future CI).
+
+---
+
+## What counts as an error
+
+Pull uses two CLI passes per target:
+
+- Log level `error` or `fatal`
+- HTTP status `500`–`508`
+
+Filter normalizes raw JSON and keeps entries matching:
+
+- Log level `error` or `fatal`
+- HTTP status `5xx`
+
+Optional: `pnpm vercel-logs:filter --include-warnings`
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| `vercel logs failed` / auth error | `vercel login` or set `VERCEL_TOKEN` |
+| Wrong team / project not found | Check `team` in `projects.registry.json`; use `vercel projects ls --scope <team>` |
+| No targets matched | Check `--sites` / `--envs` keys match registry `key` fields |
+| Empty report after errors expected | Widen with `--full` or `--since 7d`; confirm develop uses `--branch develop` |
+
+---
+
+## Maintenance
+
+- Registry: `docs/vercel-logs/projects.registry.json`
+- Scripts: `scripts/vercel-logs/`
+- Tests: `pnpm vercel-logs:test`