@se-studio/skills 1.5.5 → 1.5.6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.5.6
+
+### Patch Changes
+
+- Media wrapper entries now default their `name` (Contentful list label) to the linked asset's title when created via `create media` or `visualAssetFilename` shorthands. Document the convention in editor playbooks and skills; avoid migration-style `Wrapper for {assetId}` labels.
+
 ## 1.5.5
 
 ### Patch Changes

package/package.json

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

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

@@ -30,6 +30,8 @@ Use this skill when you need to read or edit content in Contentful CMS using the
 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:
+- **Hosted MCP:** always `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
+- **Local CLI:** `--base64` or `--url` when user approves local CLI
 - 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
@@ -369,13 +371,23 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Upload from local file, URL, or base64
-cms-edit asset upload ./poster.jpg --title "Poster"
+# Local CLI — URL or base64 (hosted MCP rejects --base64)
 cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
 cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
 
-# Upload and create a Media wrapper in one step
-cms-edit asset upload ./figure.png --with-media --media-name "Figure 1" --media-position Middle
+# Hosted MCP — always staged upload for binary files
+# cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
+# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+
+# 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>
+
+# Fix a badly labelled Media wrapper (migration "Wrapper for …" labels)
+cms-edit batch set <media-entry-id>:name=<asset-title>
+cms-edit batch save
 
 # Get asset details
 cms-edit asset info 5xKj2abcDef

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

@@ -75,6 +75,8 @@ Summarize: totals, top `issueCounts`, quick wins (alt, GIFs, stock filenames).
 
 **Fixes (user-approved only):** `cms-edit asset set-description <id> "…"` — drafts only, no publish.
 
+**Media entry labels:** The Contentful list label for a **Media** wrapper is its `name` field — **set it to the linked asset's `title`**, not `visual-{assetId}`, `Wrapper for {assetId}`, or the filename. When creating wrappers: `cms-edit create media --asset-id <id>` (name defaults to asset title) or `asset upload --with-media` (use `--media-name` only when you need a distinct label for multiple wrappers on the same asset). To fix existing entries: `cms-edit batch set <media-entry-id>:name=<asset-title>` then `batch save`.
+
 For per-page alt work: **`contentful-cms-alt-text-audit`**.
 
 ## Image guide (optional extension)

package/skills/contentful-cms-schema-org/SKILL.md

@@ -25,8 +25,8 @@ If no brand context is available, ask the user for these details.
 | About | AboutPage + Organization |
 | Service/Product | Service or Product |
 | Pricing | Product with Offer |
-| Blog listing | CollectionPage |
-| Article | Article or BlogPosting |
+| Blog listing | CollectionPage + Blog + ItemList |
+| Article | BlogPosting |
 | FAQ | FAQPage with Question/Answer |
 | Contact | ContactPage |
 | Team/People | ProfilePage or Person |
@@ -35,33 +35,59 @@ If no brand context is available, ask the user for these details.
 
 ## Phase 2: Generate Mustache Templates
 
-Create JSON-LD templates using these standard Mustache variables:
+Create JSON-LD templates using runtime variables from `buildStructuredDataContext()` in `@se-studio/core-ui` (see `packages/core-ui/src/utils/structuredDataUtils.ts`).
 
-- `{{title}}` — page/article title
-- `{{seoDescription}}` — SEO meta description
-- `{{slug}}` — page slug
-- `{{publishDate}}` — article publish date
-- `{{updatedAt}}` — last modification date
-- `{{authorName}}` — primary article author name (first in `authors`)
-- `{{#article.authors}}` — multi-author JSON-LD (`name`, `url` per author)
-- `{{heroImageUrl}}` — primary image URL
-- `{{customerName}}` — from brand context
-- `{{siteUrl}}` — from brand context
+Reference markup generators in `@se-studio/cms-seo` (`breadcrumbListMarkup`, `blogPostingMarkup`, `itemListMarkup`, etc.).
+
+### URLs and page
+
+- `{{baseUrl}}` — site origin with trailing slash (e.g. `https://www.example.com/`)
+- `{{{baseUrl}}}` — same, triple-brace for JSON-safe URLs in `@id` fields
+- `{{currentUrl}}` / `{{{currentUrl}}}` — full canonical URL of the current page
+- `{{page.title}}` — page or content title
+- `{{page.description}}` — SEO meta description
+- `{{page.slug}}` — content slug
+- `{{{page.imageUrl}}}` — OG image URL when featured image is set
+- `{{#page.breadcrumbs}}` — breadcrumb segments: `position`, `name`, optional `url`, `last`
+
+### Articles
+
+- `{{article.title}}`, `{{article.description}}`
+- `{{article.datePublished}}`, `{{article.dateModified}}` — ISO 8601 (not `article.date`)
+- `{{article.authorName}}`, `{{{article.authorUrl}}}` — primary author
+- `{{#article.authors}}` — multi-author: `name`, optional `url` per author
+- `{{{article.imageUrl}}}` — featured image URL
+
+### Person pages
+
+- `{{person.name}}`, `{{person.jobTitle}}`, `{{{person.imageUrl}}}`
+
+### Listing pages (ItemList)
+
+When the app wires `buildListingItems()` / `buildListingStructuredDataContext()` from `@se-studio/core-ui/server`:
+
+- `{{#listing.items}}` — `position`, `name`, `{{{url}}}`, `last` (for Mustache comma separation)
+
+Static brand data (organization address, social URLs, logo) belongs **in the CMS template**, not in code.
 
 ## Phase 3: Upload via cms-edit
 
 1. Check available fields:
    - `cms-edit schema page` — page content type fields
    - `cms-edit schema template` — template content type fields
-   - Look for `schemaOrg`, `jsonLd`, `structuredData`, or similar
-2. For **template-level** schemas (Organization, WebSite — shared): `cms-edit list --type template` → open → set
-3. For **page-level** schemas: open each page → set its schema field
-4. `cms-edit diff` then `cms-edit save`
+   - Look for `structuredData` or `indexPageStructuredData`
+2. For **template-level** schemas (Organization, WebSite, BreadcrumbList — shared): `cms-edit list --type template` → open → set
+3. For **article type** schemas (BlogPosting on `structuredData`, Blog/CollectionPage/ItemList on `indexPageStructuredData`): link on articleType entry
+4. For **page-level** subtype overrides (FAQPage, Product, Service): link on the page entry only
+5. `cms-edit diff` then `cms-edit save`
 
 ## Best Practices
 
 - Don't duplicate — template-level Organization schema covers all pages
-- Use specific types — `MedicalBusiness` over `LocalBusiness` if applicable
+- Link schema on **templates and types**, not on every article
+- Use specific types where they apply — `BlogPosting` for blog posts, `ProfilePage` for authors
+- BreadcrumbList `item` property: output only when `{{#url}}` is present on a segment
+- One FAQPage per URL — do not duplicate component-level and CMS-level FAQPage on the same page
 - Validate all required properties are present
 - Schema must reflect actual page content
 
@@ -72,4 +98,4 @@ Create JSON-LD templates using these standard Mustache variables:
 
 ## Related skills
 
-See the **core** skill for the full cms-edit workflow. See the **seo-descriptions** skill for meta description generation. For bulk audit/apply across all entries, schema linking, publish phases, and production verification, see **cms-seo-audit**.
+See the **core** skill for the full cms-edit workflow. See the **seo-descriptions** skill for meta description generation. For bulk audit/apply across all entries, schema linking, publish phases, and production verification, see **cms-seo-audit**.