@se-studio/skills 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @se-studio/skills
 
+## 1.5.0
+
+### Minor Changes
+
+- bc538fd: Editor-pack capabilities router (`capabilities.json`, `tasks-index`, task playbooks), batch commands (`article-tags-from-json`, `bulk-rtf-replace`, `create person` / `person-from-json`, `ensure person`), and `cms-edit project doctor`.
+
+  Hosted-first MCP: setup wizard, `cms-edit setup`, `cms-edit-setup` and `cms-edit-mcp` bins, and local install scripts removed. Editors connect via `/cms-edit` OAuth; developers use `cms-edit` CLI (`npx @se-studio/contentful-cms` aliases the CLI).
+
+  **Breaking:** Do not use local `mcpServers.cms-edit` or `cms-edit setup` — those entry points are removed.
+
+## 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/README.md

@@ -75,6 +75,7 @@ The CLI ships a **subset** of skills under `packages/contentful-cms/skills/` for
 | Canonical source (`packages/skills/skills/`) | Bundled name (`packages/contentful-cms/skills/`) |
 |---------------------------------------------|--------------------------------------------------|
 | `contentful-cms-core` | `core` |
+| `contentful-cms-editor-tasks` | `editor-tasks` |
 | `contentful-cms-templates` | `templates` |
 | `contentful-cms-setup` | `setup` |
 

package/package.json

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

package/references/contentful-cms-cms-guidelines/variant-proposal-prompt.md

@@ -76,7 +76,7 @@ Output JSON only, no explanation. Format:
   ]
 }
 
-showcaseParams keys must match the cms-edit screenshot --param format:
+showcaseParams keys must match the cms-edit preview showcase --param format:
   backgroundColour, textColour, showVisual, showLinks, showHeading, etc.
 For a flipped variant, use a separate typeName entry for "Hero Flipped".
 ```
@@ -115,7 +115,7 @@ For a flipped variant, use a separate typeName entry for "Hero Flipped".
 
 - `label` — used to name the screenshot file: `<typeName-kebab>-<label>.png`
 - `description` — included in the screenshot log and used by the evaluation step
-- `showcaseParams` — key-value pairs passed as `--param key=value` to `cms-edit screenshot`
+- `showcaseParams` — key-value pairs passed as `--param key=value` to `cms-edit preview showcase` (or `cms-capture-screenshots`)
 
 ---
 

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

@@ -7,6 +7,8 @@ description: "Use cms-edit CLI to read/edit Contentful content (open → snapsho
 
 Use this skill when you need to read or edit content in Contentful CMS using the `cms-edit` CLI tool.
 
+**Before editing:** use skill **`contentful-cms-editor-tasks`** to read `tasks-index` and the matching capability playbook for this site (hosted MCP or local `cms-edit/<site>/editor-pack/`).
+
 ## Overview
 
 `cms-edit` lets you read and edit Contentful draft content without publishing. It uses a **snapshot → ref → edit → save** workflow:
@@ -24,10 +26,14 @@ Use this skill when you need to read or edit content in Contentful CMS using the
 - Publish any entry
 - Unpublish any entry
 - Archive or delete published entries
-- Upload new assets
 
 All `save` operations create **draft** versions. A human must review and publish in Contentful.
 
+**Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). When uploading:
+- Use a **sensible fileName** and **descriptive title** (and alt text where the site uses it)
+- Avoid oversized images — width over **2000px** is usually wasteful for web (exact limits vary by project; check `asset audit` / media review guidance)
+- Prefer `--if-exists-by-filename` to avoid duplicates
+
 ## Prerequisites
 
 - `.contentful-cms.json` must exist in the project root (or ancestor directory)
@@ -576,13 +582,12 @@ cms-edit move @c3 --after @c1  # move section 3 to position 2
 cms-edit save
 ```
 
-## Screenshots
+## Visual checks
 
-The `screenshot` command captures a PNG of a component, collection, external component, person, or page using [agent-browser](https://github.com/vercel-labs/agent-browser).
+cms-edit does not capture screenshots. Use preview URL commands, then open the URL with a browser MCP (e.g. Chrome DevTools) to verify layout after edits.
 
-**Prerequisites:** `npm install -g agent-browser && agent-browser install`. For `@ref` and `--json-file`, the app must be running at `devBaseUrl`.
+**Config:** Add `devBaseUrl` to the space in `.contentful-cms.json`:
 
-**Config:** Add `devBaseUrl` to the space in `.contentful-cms.json` so the CLI knows where your dev server runs:
 ```json
 {
   "spaces": {
@@ -592,83 +597,19 @@ The `screenshot` command captures a PNG of a component, collection, external com
   }
 }
 ```
-If omitted, defaults to `http://localhost:3000` with a warning.
-
-### From session ref (full-fidelity)
-
-`cms-edit screenshot @c0` uses the app's convert API and `/cms/preview/render-json` so **all** entry types render with real converted data: component, collection, externalComponent, person. No separate "mock vs live" for refs.
-
-```bash
-# Any entry type (component, collection, externalComponent, person)
-cms-edit screenshot @c0
-
-# Full-page capture (auto-applied for component/collection)
-cms-edit screenshot @c0 --full
-
-# Just print URL
-cms-edit screenshot @c0 --url-only
-```
-
-### From JSON file (no Contentful)
-
-Screenshot an IBase* JSON file (e.g. exported from `cms-edit read @c0 --json` or a fixture). App must be running.
-
-```bash
-cms-edit screenshot --json-file path/to/component.json
-```
-
-### By type (showcase mock, no session)
-
-Uses `/cms/showcase/render` with mock data. Fast, no preview token.
 
 ```bash
-cms-edit screenshot --component HeroSimple
-cms-edit screenshot --collection CardGrid
-cms-edit screenshot @c0 --embedded --full   # when using ref with showcase-style capture
-```
-
-### Page screenshots
-
-```bash
-# Current open page (uses session root slug)
-cms-edit screenshot
+# Page (explicit slug or open session root)
+cms-edit preview url /pricing
+cms-edit open --page-slug /pricing
+cms-edit preview url
 
-# Explicit page slug
-cms-edit screenshot /pricing
-cms-edit screenshot /about-us --full
+# Component or collection showcase (mock data)
+cms-edit preview showcase --component HeroSimple
+cms-edit preview showcase --collection CardGrid --param backgroundColour=Navy
 ```
 
-### Options
-
-| Flag | Description |
-|------|-------------|
-| `--json-file <path>` | Read IBase* JSON from file and screenshot via render-json (no Contentful) |
-| `--live` | Legacy: use `/cms/preview/render?id=...` for ref (optional; @ref is already full-fidelity) |
-| `--out <path>` | Output file path (default: `./screenshot-<type>-<timestamp>.png`) |
-| `--full` | Full-page capture (passed to `agent-browser screenshot --full`) |
-| `--embedded` | Append `&embedded=true` to showcase URL (suppresses IframeHeightReporter) |
-| `--wait <ms>` | Wait milliseconds after page load before capturing (default: 500) |
-| `--url-only` | Print URL only, do not invoke agent-browser |
-| `--json` | Output `{ ok, url, file }` as JSON |
-
-### Visual diffing
-
-Use `agent-browser diff screenshot` to compare before/after a content change:
-
-```bash
-# 1. Capture baseline before editing
-cms-edit screenshot @c0 --out before.png
-
-# 2. Edit content
-cms-edit set @c0 heading "New heading"
-cms-edit save
-
-# 3. Capture after
-cms-edit screenshot @c0 --out after.png
-
-# 4. Diff
-agent-browser diff screenshot --baseline before.png after.png
-```
+For CMS guidelines batch PNG capture, use `cms-capture-screenshots` from `@se-studio/project-build` (separate from cms-edit; requires agent-browser).
 
 ## Revert
 
@@ -687,7 +628,7 @@ Note: Entries created via `add` cannot be reverted — use `remove` instead.
 Validate config and connectivity before running a workflow.
 
 ```bash
-cms-edit health   # Check config file, space config, Contentful connectivity, agent-browser
+cms-edit health   # Check config file, space config, Contentful connectivity
 ```
 
 ## Schema Inspection
@@ -906,4 +847,4 @@ cms-edit --session agent-2 open --article-slug /blog
 
 ## Related skills
 
-For templates see the **templates** skill; for navigation see the **navigation** skill; for rich text and embeds see the **rich-text** skill; for screenshots see the **screenshots** skill.
+For templates see the **templates** skill; for navigation see the **navigation** skill; for rich text and embeds see the **rich-text** skill.

package/skills/contentful-cms-editor-tasks/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: contentful-cms-editor-tasks
+description: "Route CMS editing intents to site task playbooks via tasks-index (hosted MCP resources or local editor-pack files)."
+---
+
+# Skill: cms-edit editor tasks
+
+Use this skill **before any Contentful edit** to pick the right capability playbook for the user's goal. Do not improvise workflows — read the site brain first.
+
+## Pit-of-success order
+
+1. **tasks-index** — which tasks apply on this site
+2. **capabilities** — what content types and bulk mechanisms exist
+3. **checklist** — pre-flight checks
+4. **overview** + **routing** — site rules and URL shapes
+5. **task-*** playbook — steps, confirmation gates, out-of-scope
+6. **components-index** — when creating or editing page content
+
+## Hosted (Claude Integrations + OAuth)
+
+Claude cannot read `cms-edit://customer/*` URIs directly — use the MCP tools:
+
+```text
+cms_edit ["customer", "tasks-index"]
+cms_edit ["customer", "capabilities"]
+cms_edit ["customer", "checklist"]
+cms_edit ["customer", "task-create-article"]   # example — pick from tasks-index
+```
+
+Or `cms_edit_customer` with resource `tasks-index`, then the `task-*` name from the index.
+
+**Never pass `--space`** on hosted MCP — the deployment is already bound to one site.
+
+After connect, verify with: `Read the cms-edit guide and tasks-index`.
+
+## Local (Cursor / Grok / Codex / CLI)
+
+Read committed files in the customer repo (paths vary by layout):
+
+| Layout | Editor pack |
+|--------|-------------|
+| Single-site | `cms-edit/editor-pack/` |
+| Multi-site | `cms-edit/<site>/editor-pack/` |
+
+Minimum reads:
+
+- `capabilities.json`
+- `tasks-index.md`
+- `checklist.md`
+- Matching `task-*.md` for the user's intent
+
+Then use **`contentful-cms-core`** for `cms-edit` CLI commands.
+
+## Confirmation gates (all tasks)
+
+Capability playbooks require:
+
+1. **Propose** scope to the user — wait for approval
+2. **Dry-run** when available (`--dry-run`, `bulk-rtf-replace --dry-run`, etc.)
+3. **`diff`** before every `save`
+4. **Summarize** what changed; remind that publish is manual in Contentful
+
+## Media default
+
+**Search and reuse assets first** (`index sync` → `asset search`). Upload only when no match; use `--if-exists-by-filename` when uploading.
+
+## When the pack is stale
+
+Run `contentful-cms-regenerate-editor-pack` after:
+
+- New component/collection registrations
+- `docs/cms-guidelines/**` changes
+- `constants.ts` routing changes
+
+Then `cms-edit project doctor --project-config cms-edit/<site>/project.json`.
+
+## Related skills
+
+| Skill | When |
+|-------|------|
+| `contentful-cms-core` | CLI command reference |
+| `contentful-cms-setup` | First-time hosted MCP connect |
+| `contentful-cms-regenerate-editor-pack` | Refresh editor-pack in git |

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

@@ -235,6 +235,5 @@ Report the output paths and any images that had no usages (potential orphans).
 
 ## Related skills
 
-- **core**: Full cms-edit workflow reference
+- **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
-- **contentful-cms-screenshots**: Take live screenshots of pages for reference

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/contentful-cms-seo-descriptions/SKILL.md

@@ -20,10 +20,10 @@ If no brand context is available, ask the user about their brand voice and targe
    a. **Read page content** using `fetch_page_markdown` (from the site-workflows MCP server) to understand what the page covers
    b. **Check current SEO**:
       - `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
-      - `cms-edit read @page seoDescription` (or `read @page` for all fields)
+      - `cms-edit snapshot` then `cms-edit read @p0 description` (or `read @p0` for all fields)
    c. **Analyse** the page — primary purpose, problem it solves, desired user action
    d. **Generate** a meta description following the guidelines below
-   e. `cms-edit set @page seoDescription "new description"`
+   e. `cms-edit set @p0 description "new description"`
    f. `cms-edit diff` then `cms-edit save`
 
 ## Meta Description Guidelines

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

@@ -1,26 +1,19 @@
 ---
 name: contentful-cms-setup
-description: "Guide a user through installing and configuring the cms-edit MCP server for Claude Desktop."
+description: "Guide a user through connecting hosted cms-edit MCP for Claude (Integrations + OAuth)."
 ---
 
 # Skill: cms-edit Setup
 
-Use this skill when the user wants to install or configure the `cms-edit` MCP server so Claude Desktop can read and edit Contentful content.
+Use this skill when the user wants to connect Claude to their Contentful site via **hosted cms-edit MCP**.
 
-## Choose the setup path first
-
-| Path | When to use |
-|------|-------------|
-| **Hosted (Integrations)** | Content editor; SE sent an onboarding URL (e.g. `/cms-edit`); no Node.js |
-| **Local (setup wizard)** | Developer; multi-space; or no hosted deployment |
-
-Ask which applies if unclear.
+Local stdio MCP and the setup wizard are **not supported**. Editors connect through the site's `/cms-edit` onboarding flow.
 
 ---
 
 ## Hosted setup (Claude Integrations + OAuth)
 
-Use when SE sent an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`). Do **not** run the setup wizard.
+Use when SE sent an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`).
 
 ### Step 1: Connect to Claude
 
@@ -34,93 +27,34 @@ Full editor guide: `packages/contentful-cms/HOSTED.md`
 
 ### Step 2: Verify
 
-In Claude, ask to read the cms-edit guide or verify the connection. If `cms_edit` returns content, setup is complete.
+In Claude, ask to read the cms-edit guide and **tasks-index**, then verify the connection. If `cms_edit` returns content, setup is complete.
+
+Use skill **`contentful-cms-editor-tasks`** for the tasks-index → capability playbook workflow.
 
 **Reconnect:** Settings → Integrations → Connect again if the connection stops working.
 
 ---
 
-## Local setup (setup wizard)
-
-## Overview
-
-The setup wizard handles everything automatically:
-- Collects the Contentful Management Token
-- Discovers spaces and environments via the Contentful API
-- Writes `~/.contentful-cms.json`
-- Updates the Claude Desktop config to register the `cms-edit` MCP server
-
-## Prerequisites
-
-The user needs:
-1. **Node.js** installed (LTS version from [nodejs.org](https://nodejs.org))
-2. **A Contentful Management Token** — see Step 1 below
-
-## Step 1: Get a Management Token
-
-Tell the user:
-
-> To get your Contentful Management Token:
-> 1. Log in to [contentful.com](https://app.contentful.com)
-> 2. Go to **Settings → API keys**
-> 3. Click the **Content management tokens** tab
-> 4. Click **Generate personal token**, name it `Claude Desktop`, and click **Generate**
-> 5. Copy the token — you won't see it again
-
-Ask them to confirm they have the token before continuing.
+## Developers (CLI + skills, not local MCP)
 
-## Step 2: Run the Setup Wizard
+For engineering work in a site repo (Cursor, Grok, terminal):
 
-Tell the user to open a terminal and run:
+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
+4. Read `cms-edit/<site>/editor-pack/tasks-index.md` before editing content
 
-```bash
-npx @se-studio/contentful-cms@latest setup
-```
+Do **not** register a local `mcpServers.cms-edit` entry in Claude Desktop — use the hosted connector URL instead.
 
-Walk them through what each prompt means:
-
-| Prompt | What to enter |
-|--------|--------------|
-| **Contentful Management Token** | The token they just copied (input will be hidden) |
-| **Which Contentful space?** | Only appears if the token has multiple spaces — pick the one they want to connect |
-| **Which environment?** | Auto-selects `master`; only asks if no `master` environment exists |
-| **Short name for this project** | A slug like `my-project` or `om1` — used as the key in the config file |
-| **Staging site URL** | Optional — their Vercel preview URL (e.g. `https://my-project.vercel.app`) |
-| **Vercel bypass token** | Optional — only if their staging site has deployment protection |
-
-## Step 3: Restart Claude Desktop
-
-After the wizard completes, tell the user:
-
-> Fully quit Claude Desktop and reopen it.
-> - **Mac:** Right-click the Dock icon → **Quit** (closing the window isn't enough)
-> - **Windows/Linux:** Close and reopen from the Start menu
-
-## Step 4: Verify
-
-Once they've reopened Claude Desktop, verify the setup worked by using the `cms_edit` tool:
-
-```
-cms_edit ["open", "/"]
-```
-
-If it returns a page structure, setup is complete. If it errors, see Troubleshooting below.
+---
 
 ## Troubleshooting
 
-**"Invalid management token"**
-→ The token may have been copied incorrectly or already expired. Generate a new one in Contentful and run the wizard again.
-
-**"No spaces found"**
-→ The token doesn't have access to any spaces. Check Contentful's token permissions — it needs at least read access to one space.
-
-**`cms_edit` tool not available after restart**
-→ Check the Claude Desktop config was written correctly:
-- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-- Linux: `~/.config/Claude/claude_desktop_config.json`
+**OAuth / sign-in fails**
+→ Confirm the user was invited to the Contentful space and is signing in with the correct account.
 
-It should contain an `mcpServers.cms-edit` entry. If missing, run the wizard again.
+**`cms_edit` tool not available**
+→ Reconnect via `/cms-edit` or Claude Integrations. Remove any legacy local MCP or `.mcpb` extension entries.
 
-**Adding another space**
-→ Run `npx @se-studio/contentful-cms@latest setup` again — it merges the new space into the existing config.
+**Connection works but wrong site**
+→ Each connector URL is site-specific; use the URL from the project's `/cms-edit` page.

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

package/skills/site-workflows-new-project/SKILL.md

@@ -83,6 +83,16 @@ The user's email address is [USER_EMAIL].
 
 # currentDate
 Today's date is [CURRENT_DATE].
+
+## CMS editing (cms-edit)
+
+Before any Contentful content edit:
+
+1. Read `cms-edit/<site>/editor-pack/capabilities.json` and `tasks-index.md` (skill: `contentful-cms-editor-tasks`)
+2. **Hosted (Claude Integrations):** connect to the site's MCP URL; read `tasks-index` via `cms_edit ["customer", "tasks-index"]` — never pass `--space`
+3. **Local / Cursor / Grok:** `npx skills add @se-studio/skills` — use `contentful-cms-editor-tasks` then `contentful-cms-core`
+4. Regenerate editor pack after registration or guideline changes (`contentful-cms-regenerate-editor-pack`)
+5. Run `cms-edit project doctor --project-config cms-edit/<site>/project.json` after pack changes
 ```
 
 ---

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

@@ -1,46 +0,0 @@
----
-name: contentful-cms-screenshots
-description: "Capture screenshots of components, collections, pages or persons via cms-edit."
----
-
-# Skill: contentful-cms — Screenshots
-
-Use this skill when capturing **screenshots** of components, collections, pages, or persons with `cms-edit`. **Requires agent-browser** to be installed.
-
-## Prerequisites
-
-- `npm install -g agent-browser && agent-browser install`
-- Without agent-browser, the command exits with install instructions (use `--url-only` to only print the URL).
-- For `@ref` and `--json-file`: the app must be running at `devBaseUrl` (see `.contentful-cms.json`).
-
-## Commands
-
-- **From session ref** (full-fidelity): `cms-edit screenshot @c0` — uses the convert API and `/cms/preview/render-json` so **all** entry types render with real data: component, collection, externalComponent, person. Add `--full` for full-page capture (auto-applied for component/collection).
-- **From JSON file** (no Contentful): `cms-edit screenshot --json-file path/to/entry.json` — reads an IBase* JSON (e.g. from `read @c0 --json` or an export), base64-encodes it, and opens `/cms/preview/render-json?data=...`. Use to validate or screenshot without a session or preview token.
-- **By type** (no session, mock): `cms-edit screenshot --component HeroSimple`, `cms-edit screenshot --collection CardGrid` — uses `/cms/showcase/render` with mock data.
-- **Page**: `cms-edit screenshot` (current open page) or `cms-edit screenshot /resources/publications/other/my-slug`
-- **URL only** (no agent-browser needed): `cms-edit screenshot @c0 --url-only`
-
-## Target path: use the full site path
-
-When passing a path target (e.g. `cms-edit screenshot /path`), the target must be the **full path** on the site — not just the final slug segment. cms-edit prepends `devBaseUrl` from your config to build the URL.
-
-> **Correct:** `cms-edit screenshot /resources/publications/other/my-article`
-> **Incorrect:** `cms-edit screenshot /my-article` ← will 404 if the site expects a longer path
-
-Check the site's URL structure (e.g. `/resources/publications/<type>/<slug>`) and use the complete path. The `devBaseUrl` is set in `.contentful-cms.json` (defaults to `http://localhost:3000` if not configured).
-
-## Mock vs live (type-only mode only)
-
-When using `--component <type>` or `--collection <type>` (no session), the default is **mock** (showcase). Use `--live` with a ref to prefer the legacy direct preview URL; for `@ref`, full-fidelity is already the default via convert → render-json.
-
-- **Mock:** `/cms/showcase/render` with mock data; fast, no preview token.
-- **Live** (with ref): `cms-edit screenshot @c0 --live` — uses `/cms/preview/render?id=...`; equivalent for component/collection/externalComponent to the default @ref path.
-
-## Checking your work
-
-After editing content, run `cms-edit screenshot @ref` or `cms-edit screenshot /slug` to capture and verify. Use `--out before.png` / `--out after.png` and `agent-browser diff screenshot` for visual diffing. To validate a component from exported JSON, use `cms-edit screenshot --json-file <path>`.
-
-## Related skills
-
-See the **core** skill for session, open, and snapshot.