@se-studio/skills 1.7.16 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.8.0
+
+### Minor Changes
+
+- 104ce64: Add `cms-edit patterns generate` to census published page and article stacks from the Delivery API, ship them as `page-patterns` in the editor pack, and teach editor skills to read families before cloning.
+
+## 1.7.17
+
+### Patch Changes
+
+- 6fbdfd6: cms-edit media intake: stop teaching raster `asset upload`, surface staged GET 405 as a host bump (not a retry/UI fallback), and document the SE Studio local media loop.
+
 ## 1.7.16
 
 ### Patch Changes

package/package.json

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

package/references/contentful-cms-editor-playbooks/PATTERNS.md

@@ -91,6 +91,8 @@ Brightline excerpt:
 
 Fetch live markdown when `website.markdownAccess` is enabled: `https://<prod><path>.md`
 
+**Typical content stack** must match `page-patterns` (required types + clone slug). Shared blocks listed there are **edit in place** — do not fork. Nested families in `page-patterns` (child URL prefixes) need their own playbook, not one parent stack.
+
 ## Tier system (Brightline)
 
 ### P0 — ship first
@@ -150,6 +152,7 @@ Site `articles.md` must name **this site’s** body components. Do not paste SE
 | `people.md` | `enablePerson=true` — team profiles, author import |
 | `blog-tag-matrix.md` | Complex tag governance (Brightline) |
 | `site-facts.json` | Canonical support email, phone — becomes `site-facts` resource |
+| `page-patterns.json` / `page-patterns.md` | Live Delivery census (`cms-edit patterns generate`) — clone slugs, stacks, shared blocks |
 | `tasks/*.md` only | Overrides for core tasks (e.g. `import-blog-tag-matrix`) |
 | `case-study-from-package.md` (SE) | Optional specialized multi-block package playbook + hosted example |
 

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

@@ -7,7 +7,9 @@ description: "Edit Contentful drafts via hosted cms-edit MCP (open → snapshot
 
 Use this skill when you need to read or edit content in Contentful using **hosted cms-edit MCP** (`cms_edit` with an `args` array). Command names match the old CLI (`open` → `snapshot` → `read` → `set`/`rtf` → `diff` → `save`).
 
-**Do not** run the local `cms-edit` binary for content. It refuses `open`, `save`, `set`, and other content commands. Local CLI is only for `host`, `editor-pack`, `project`, `schema`, and `guide`.
+**Do not** run the local `cms-edit` binary for content. It refuses `open`, `save`, `set`, and other content commands. Local CLI is only for `host`, `editor-pack`, `patterns`, `project`, `schema`, and `guide`.
+
+**Page patterns (local):** `cms-edit patterns generate --project-config cms-edit/<site>/project.json` writes live family stacks from the Delivery API. Hosted agents read `cms-edit://customer/page-patterns` after editor-pack generate.
 
 **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/`).
 
@@ -33,7 +35,7 @@ All `save` operations create **draft** versions. A human must review and publish
 **Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). When uploading:
 - **Raster/video:** `cms_edit_request_staged_upload` → curl → `cms_edit_media` prepare (`stagedUploadIds`) → wait → catalog → import with real alt. Never `asset upload --staged/--url/--base64` for jpeg/png/webp/gif/mp4.
 - **SVG/PDF/Lottie:** `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
-- **HtmlComponent / large JSON:** `cms_edit_request_staged_upload` with `kind=text` or `kind=json` → curl → `set --staged`, `rtf --staged`, `create from-json --staged`, or `apply from-json --staged`. Hosted MCP rejects inline `--json`/`--content` over 8192 bytes.
+- **HtmlComponent / large JSON:** `cms_edit_request_staged_upload` with `kind=text` or `kind=json` → curl → `set --staged`, `rtf --staged`, `create from-json --staged`, or `apply from-json --staged`. Hosted MCP rejects inline `--json`/`--content` over 8192 bytes. If the wrapper schema has no `kind`, use `cms_edit` `["staged-upload", "request", "--kind", "json", "--file-name", "...", "--mime", "application/json"]` (or `--kind text`), then curl, then `--staged`.
 - 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
@@ -374,11 +376,10 @@ cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
 # Raster/video: cms_edit_media prepare → wait → catalog → import (video: import only).
+# Do not `asset upload` jpeg/png/webp/gif/mp4. Do not convert GIF/MP4 with local ffmpeg.
+# Animated GIF: leave as GIF; pipeline emits gif-converted MP4 for Media mute-loop, not featuredImage.
 # SVG/PDF/Lottie: cms_edit_request_staged_upload → curl → asset upload --staged
 
-# Upload and create a Media wrapper in one step (--media-name defaults to asset title)
-cms-edit asset upload ./figure.png --with-media --media-position Middle
-
 # Create a Media wrapper for an existing asset (name defaults to asset title)
 cms-edit create media --asset-id <asset-id>
 

package/skills/contentful-cms-create-editor-playbooks/SKILL.md

@@ -65,11 +65,20 @@ Check:
 
 ### Page inventory
 
-Build a **category table** (URL prefix → human label → clone reference slug):
+Build the category table from **Delivery page-patterns**, not sitemap prefixes alone:
 
-1. Production sitemap: `curl -s https://<prod>/sitemap.xml` or app's `pnpm sitemap-validate` config
-2. Group paths by prefix (`/resources/`, `/insights/`, `/what-we-treat/`, etc.)
-3. Pick 1–3 **canonical clone sources** per category (`peek --page-slug`, live `.md` URLs)
+```bash
+cms-edit patterns generate --project-config cms-edit/<site>/project.json
+# writes docs/cms-editor/<projectKey>/page-patterns.json + page-patterns.md
+```
+
+1. Read `page-patterns.md` — each **family** is a candidate playbook (including nested children)
+2. Use each family's `cloneSlug` as the canonical clone source
+3. Nested children (e.g. `what-we-treat/anxiety/types`) get their **own** specialized playbook
+4. Flags: `low-majority-campaign` / `unique-compositions` → document the skeleton and clone the nearest sibling; do **not** invent one canonical stack. `empty-body` article types are template-owned.
+5. Sitemap / `peek` only to confirm public URLs and copy, not to discover families
+
+Requires `CONTENTFUL_ACCESS_TOKEN` (Delivery). If generate cannot run, say so and fall back to sitemap prefixes.
 
 ### CMS capabilities
 
@@ -86,10 +95,11 @@ Read generated `capabilities.json` (or editor-pack copy) for `content.pages`, `c
 
 ### Skip rules
 
-| Condition | Skip |
-|-----------|------|
-| `enablePerson === false` | `people.md` (SE website — team via **Person** entries in collections, not `/people/` routes) |
-| No distinct URL category with ≥3 pages | Specialized playbook — fold into `pages.md` |
+| Condition | Action |
+|-----------|--------|
+| `enablePerson === false` | Skip `people.md` (SE website — team via **Person** entries in collections, not `/people/` routes) |
+| Unique high-value hub (e.g. `/schools`) even if n=1 | Still document in `pages.md` with its live stack |
+| No distinct URL family with ≥3 pages **and** no useful unique hub | Fold into `pages.md` — no specialized playbook |
 | Page type is engineering-only | Document in `pages.md` "out of scope" instead |
 
 ## Phase 2 — Plan playbook tiers

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

@@ -13,8 +13,9 @@ Use this skill **before any Contentful edit** to pick the right capability playb
 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
+5. **page-patterns** — live slug/article-type families, clone slugs, shared blocks (`cms-edit://customer/page-patterns`)
+6. **task-*** playbook — steps, confirmation gates, out-of-scope
+7. **components-index** — when creating or editing page content
 
 ## Hosted (Claude Integrations + OAuth)
 
@@ -47,6 +48,7 @@ Minimum reads:
 - `capabilities.json`
 - `tasks-index.md`
 - `checklist.md`
+- `page-patterns.md` (match the URL or article type to a family before clone)
 - Matching `task-*.md` for the user's intent
 
 Then use **`contentful-cms-core`** for `cms-edit` CLI commands.

package/skills/contentful-cms-regenerate-editor-pack/SKILL.md

@@ -62,6 +62,14 @@ pnpm cms-edit:editor-pack
 
 **Generic / multi-site:**
 
+If Delivery credentials are in `.env.local` and `docs/cms-editor/<projectKey>/page-patterns.md` is missing or stale, refresh families first:
+
+```bash
+cms-edit patterns generate --project-config cms-edit/<site>/project.json
+```
+
+Then:
+
 ```bash
 cms-edit editor-pack generate --project-config cms-edit/<site>/project.json
 ```

package/skills/se-marketing-sites-handling-media/SKILL.md

@@ -40,34 +40,40 @@ import { Visual } from '@se-studio/core-ui';
 You **MUST** provide `visualSizes` to ensure the browser loads the correct image size. This uses the `sizes` attribute.
 
 ```typescript
-import { calculateVisualSizes } from '@se-studio/core-ui';
+import { calculateVisualSizes, cardVisualSizes, heroVisualSizes } from '@se-studio/core-ui';
 
-// Example: Full width on mobile, 50% width on laptop
+const heroSizes = heroVisualSizes(); // defaultSize 100vw; no breakpoints
+const cardSizes = cardVisualSizes({ columns: 3, mobileColumns: 2 });
 const sizes = calculateVisualSizes(1, { laptop: 0.5 });
 
-<VisualComponent
-  visual={visual}
-  visualSizes={sizes}
-/>
+<VisualComponent visual={heroVisual} visualSizes={heroSizes} />
+<VisualComponent visual={cardVisual} visualSizes={cardSizes} />
+<VisualComponent visual={splitVisual} visualSizes={sizes} />
 ```
 
-*   `1`: 100vw (Mobile default)
-*   `laptop: 0.5`: 50vw (Laptop breakpoint)
+*   `heroVisualSizes()`: full-bleed — `defaultSize` `100vw`, no breakpoints (same as `calculateVisualSizes(1)`). `PictureComponent` keeps the full next/image srcset ladder.
+*   `cardVisualSizes({ columns, mobileColumns })`: mobile column vw; laptop `min(columnVw, capPx)`; desktop px cap `round(contentMax / columns)` (3-up → 480px at 1440). Match `columns` / `mobileColumns` to the real grid (example-empty LinkCard is 4-up). Capped sizes also bound the `/_next/image` srcset (384, 640, 828, 1080, plus one large ≤1504 already in the app config). Do not invent `w` values or shrink global `deviceSizes`.
+*   `calculateVisualSizes(1, { laptop: 0.5 })`: `1` = 100vw mobile; `laptop: 0.5` = 50vw. Callers stay vw-only (full srcset, not the card subset).
 
 ### visualSizes Must Mirror Col-Span
 
 `visualSizes` **must** match the visual's layout (col-span, container width). The browser uses these values to pick the right image size.
 
+*   **Card grids**: `cardVisualSizes({ columns, mobileColumns })` — use the actual column counts (e.g. 4-up `centered-grid-4` → `{ columns: 4, mobileColumns: 4 }`; 3-up with 2-up mobile → `{ columns: 3, mobileColumns: 2 }`).
+*   **Full-bleed / hero**: `heroVisualSizes()` or `calculateVisualSizes(1)`.
 *   **Rule**: `col-span-N` in a 12-col grid → use `N/12` (e.g. 6 cols → 0.5, 5 cols → 5/12).
-*   **Full width** (`col-span-full`) → use `1`.
-*   **First arg** = mobile/default; breakpoint keys (`laptop`, `tablet`, `desktop`) = that breakpoint.
+*   **Full width** (`col-span-full`) → use `1` / `heroVisualSizes()`.
+*   **First arg** of `calculateVisualSizes` = mobile/default; breakpoint keys (`laptop`, `tablet`, `desktop`) = that breakpoint.
 *   **Common mistake**: Reversing mobile vs laptop. If mobile is full width and laptop is smaller, use `(1, { laptop: 0.5 })`, **not** `(0.5, { laptop: 1 })`.
 *   **Fixed-size icons** (~96–128px): use small ratios like `0.2`–`0.25`; **never** use values > 1 (e.g. `(100)` is invalid and causes massive over-fetch).
 *   **Example table**:
 
 | Layout | visualSizes |
 |--------|-------------|
-| Full width | `(1)` |
+| Full width / hero | `heroVisualSizes()` or `(1)` |
+| 4-up cards (e.g. `centered-grid-4`) | `cardVisualSizes({ columns: 4, mobileColumns: 4 })` |
+| 3-up cards (2-up mobile) | `cardVisualSizes({ columns: 3, mobileColumns: 2 })` |
+| 2-up cards | `cardVisualSizes({ columns: 2 })` |
 | 6 cols on laptop, full on mobile | `(1, { laptop: 0.5 })` |
 | 5 cols on laptop, full on mobile | `(1, { laptop: 5/12 })` |
 | 2 cols in 12 on laptop, half on mobile | `(0.5, { laptop: 2/12 })` |