@se-studio/skills 1.4.4 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @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
+
+- 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

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.4",
+  "version": "1.5.1",
   "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/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

@@ -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)
@@ -273,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
@@ -430,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.
@@ -457,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
@@ -475,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
@@ -485,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
 
@@ -560,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."
@@ -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,125 +597,57 @@ 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
-
-# Explicit page slug
-cms-edit screenshot /pricing
-cms-edit screenshot /about-us --full
-```
-
-### 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
+# Page (explicit slug or open session root)
+cms-edit preview url /pricing
+cms-edit open --page-slug /pricing
+cms-edit preview url
 
-# 4. Diff
-agent-browser diff screenshot --baseline before.png after.png
+# Component or collection showcase (mock data)
+cms-edit preview showcase --component HeroSimple
+cms-edit preview showcase --collection CardGrid --param backgroundColour=Navy
 ```
 
-## Revert
+For CMS guidelines batch PNG capture, use `cms-capture-screenshots` from `@se-studio/project-build` (separate from cms-edit; requires agent-browser).
 
-Field-level undo — restore fields to their original values from when the session was opened.
+## Undo changes
 
-```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)
-```
+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.
 
-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
 
 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
 
-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
@@ -722,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`.
@@ -882,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.
@@ -906,4 +840,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-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,15 +15,15 @@ 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**:
       - `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. 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
 
-```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/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/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-image-guide/SKILL.md

@@ -1,240 +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 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-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.