@se-studio/skills 1.0.38 → 1.0.40

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @se-studio/skills
 
+## 1.0.40
+
+### Patch Changes
+
+- Add ordered `article.authors` CMS field support (first author = primary) with shared helpers in `@se-studio/core-data-types`: `getArticleAuthors`, `getPrimaryArticleAuthor`, `formatArticleAuthorNames`, and `normalizeResolvedArticleAuthors`. Legacy single `author` remains populated as `authors[0]` during migration.
+
+  **@se-studio/contentful-rest-api** — Resolve and normalize `authors` on full articles and article links; include `fields.authors` in link-only fetches. Related-articles scoring matches any listed co-author.
+
+  **@se-studio/core-ui** — Structured data context exposes multi-author JSON-LD (`article.authors`); related-articles fallback uses all article authors. Omits authors without a display name.
+
+  **@se-studio/search** / **@se-studio/markdown-renderer** — Index and export comma-separated multi-author bylines via `formatArticleAuthorNames`.
+
+  **@se-studio/contentful-cms** — Fetch and audit entry trees traverse `authors` links; shared `linkedEntryFields` module deduplicates traversal logic.
+
+  **@se-studio/skills** — Add `contentful-cms-sync-schema` skill; document multi-author Schema.org variables.
+
+  Run migration `scripts/migrations/17-add-article-authors.js` on live spaces after deploying packages.
+
+## 1.0.39
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.0.38
 
 ### Patch Changes

package/package.json

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

package/skills/contentful-cms-alt-text-audit/SKILL.md

@@ -17,7 +17,7 @@ If no brand context is available, ask the user about any brand-specific terms be
 
 1. **Get all pages**: `cms-edit sitemap`
 2. **For each page** (or a specific page if the user specified one):
-   a. `cms-edit open /<slug>`
+   a. `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
    b. `cms-edit snapshot` — identify components with visual/image/media fields
    c. For each image-bearing component:
       - `cms-edit read @ref` to inspect fields

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

@@ -40,20 +40,23 @@ To get the path to the full README (e.g. for an LLM to read): `cms-edit --docs`
 ### Step 1: Open a page
 
 ```bash
-# By slug
-cms-edit open /pricing
+# By page slug (trailing slash OK)
+cms-edit open --page-slug /pricing
+
+# By page cmsLabel (when editors use cmsLabel heavily)
+cms-edit open --page-cms-label "Pricing page"
 
 # By slug with explicit space
-cms-edit --space om1 open /pricing
+cms-edit --space om1 open --page-slug /pricing
 
 # By Contentful entry ID
-cms-edit open 4xKj2abcDef --id
+cms-edit open --id 4xKj2abcDef
 
 # Home page (slug is 'index')
-cms-edit open /
+cms-edit open --page-slug /
 ```
 
-**Slug `open`:** matches **page**, **article**, **articleType**, and **tag** by `fields.slug` (in that order; first match wins). For **template** or **navigation**, use `open <id> --id` or `cms-edit nav open`.
+**Flat lookup flags:** provide **exactly one** primary flag per `open` / `resolve` / `nav open`. See `cms-edit help lookup`. Run `cms-edit index sync` so catalog types resolve from the local index.
 
 ### Step 2: Read the snapshot
 
@@ -236,7 +239,7 @@ Same as Component plus:
 
 When adding body content and a CTA (e.g. PDF download) to an article:
 
-1. `cms-edit open <article-slug>` (or `open <id> --id`)
+1. `cms-edit open --article-slug <slug>` (or `open --id <id>`)
 2. Set body: `cms-edit rtf @<ref> body --markdown "..."` or `--markdown --file path/to.md`. If you need to add a body component first, use `add` then `rtf`.
 3. `cms-edit add CTA --target bottomContent`
 4. Set CTA links: use `--type external --label "Download PDF" --href <url>` for an external PDF URL, or `--type download --label "Download PDF" --asset-id <asset-id>` for a Contentful asset (get the ID from `cms-edit asset search "..."` or `asset info <id>`).
@@ -341,13 +344,14 @@ cms-edit set @c5 links linkId4 --links --append
 
 ## Assets
 
-**Content index:** Run `cms-edit index sync` once per space before asset search, media-by-filename list, asset audit, or `--if-exists-by-filename`. The same sync also indexes **templates**, **articleType**, **tagType**, and **tag** for fast `list --type` and taxonomy `--if-not-exists`. Default sync uses the **Preview API** (draft content). See `cms-edit help index-sync`.
+**Content index:** Run `cms-edit index sync` once per space before asset search, media-by-filename list, asset audit, or `--if-exists-by-filename`. The same sync indexes the full **content catalog** (pages, articles, taxonomy, navigation, templates) for fast `list`, `open`, and `resolve`. Default sync uses the **Preview API** (draft content). See `cms-edit help index-sync` and `cms-edit help lookup`.
 
 ```bash
 cms-edit index sync
 cms-edit index status
+cms-edit list --type page
 cms-edit list --type template
-cms-edit resolve --type tagType --slug topic
+cms-edit resolve --tag-type-slug topic
 
 # Published-only index (optional)
 cms-edit index sync --published
@@ -381,8 +385,8 @@ JSON output for upload (`CMS_EDIT_JSON=1`): `{ ok, id, fileName, url, mediaId?,
 ## Navigation
 
 ```bash
-# Open a navigation entry
-cms-edit nav open main-navigation
+# Open a navigation entry (navigation uses `name`, not slug)
+cms-edit nav open --nav-name "Main navigation"
 
 # Add a new item
 cms-edit nav add --label "Pricing" --slug /pricing
@@ -414,7 +418,10 @@ cms-edit create article --slug /blog/my-post --title "My Post" --article-type-id
 # Create taxonomy entries (draft only)
 cms-edit create tag-type --slug conference-venue --name "Conference Venue"
 cms-edit create article-type --slug resources/publications --name "Publications"
-cms-edit create tag --slug poster-presentation --name "Poster Presentation" --tag-type presentation-type
+cms-edit create tag --slug poster-presentation --name "Poster Presentation" --tag-type-slug presentation-type
+# cmsLabel defaults to "<tagType name> — <tag name>" when --cms-label omitted
+cms-edit create tag --slug easl-congress-2026 --name "EASL Congress 2026" --tag-type publication-source \
+  --description "Research presented at EASL Congress 2026." --featured-image <logoAssetId>
 
 # Full fields via JSON
 cms-edit create tag --json-file tag.json --tag-type presentation-type --if-not-exists
@@ -424,7 +431,8 @@ 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
+cms-edit ensure tag --slug asco-2025 --name "ASCO 2025" --tag-type conference-venue \
+  --description "Annual ASCO conference." --featured-image <logoAssetId>
 ```
 
 See `cms-edit help fields-taxonomy` and `cms-edit help taxonomy-from-json` for field reference and batch schema.
@@ -433,10 +441,11 @@ See `cms-edit help fields-taxonomy` and `cms-edit help taxonomy-from-json` for f
 
 ```bash
 # Resolve taxonomy IDs without a session
-cms-edit resolve --type tag-type --slug presentation-type
+cms-edit resolve --tag-type-slug presentation-type
+cms-edit resolve --tag-name "ASCO 2025" --tag-type-name "Conference Venue"
 ```
 
-`resolve --type` accepts `page`, `article`, `articleType`, `tagType`, `tag` (kebab aliases such as `tag-type`).
+Use flat flags: `--page-slug`, `--article-cms-label`, `--tag-slug`, `--template-label`, etc. (`cms-edit help lookup`).
 
 ## Search and Discovery
 
@@ -455,11 +464,11 @@ 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
 
 # Resolve any entry or asset by ID (no open session required)
-cms-edit resolve 4xKj2abcDefGhijK                 # entry: shows type, title, slug, status
-cms-edit resolve 7pQrStuvWxyzAbc                  # asset: shows title, fileName, URL
-cms-edit resolve --type tagType --slug presentation-type
-cms-edit resolve --type tag --slug asco-2025
-cms-edit resolve <id> --json                       # full Contentful object
+cms-edit resolve --id 4xKj2abcDefGhijK             # entry: shows type, title, slug, status
+cms-edit resolve --id 7pQrStuvWxyzAbc              # asset: shows title, fileName, URL
+cms-edit resolve --tag-type-slug presentation-type
+cms-edit resolve --tag-slug asco-2025 --tag-type-slug conference-venue
+cms-edit resolve --tag-type-slug presentation-type --json
 
 # Find Media entries by asset
 cms-edit list --type media --asset-id 7pQrStuvWxyzAbc
@@ -479,8 +488,8 @@ cms-edit resolve <tag-entry-id>
 
 ```bash
 # Specify space explicitly
-cms-edit --space brightline open /home
-cms-edit --space om1 open /pricing
+cms-edit --space brightline open --page-slug /home
+cms-edit --space om1 open --page-slug /pricing
 ```
 
 Or set `CMS_EDIT_SPACE=om1` environment variable.
@@ -489,7 +498,7 @@ Or set `CMS_EDIT_SPACE=om1` environment variable.
 
 ```bash
 # 1. Open the page
-cms-edit open /about-us
+cms-edit open --page-slug /about-us
 
 # 2. Find the hero component
 cms-edit snapshot
@@ -515,7 +524,7 @@ cms-edit save
 
 ### Update an existing article
 ```bash
-cms-edit open /blog/old-title --id  # or by slug
+cms-edit open --article-slug /blog/old-title  # or cms-edit open --id <id>
 cms-edit set @p0 title "New Article Title"   # @p0 works in article sessions too
 cms-edit set @p0 slug new-article-slug
 cms-edit set @p0 description "Updated description"
@@ -524,7 +533,7 @@ cms-edit save
 
 ### Add a new section to a page
 ```bash
-cms-edit open /products
+cms-edit open --page-slug /products
 cms-edit types component  # discover what's available
 cms-edit add CTA --after @c3
 cms-edit set @c4 heading "Ready to get started?"
@@ -535,7 +544,7 @@ cms-edit save
 
 ### Reorder page sections
 ```bash
-cms-edit open /home
+cms-edit open --page-slug /home
 cms-edit snapshot  # see current order
 cms-edit move @c3 --after @c1  # move section 3 to position 2
 cms-edit save
@@ -682,8 +691,8 @@ cms-edit sitemap --include page,article  # Include articles too
 Inspect a page without affecting your active session.
 
 ```bash
-cms-edit peek /pricing   # Show snapshot of /pricing; your active session is unchanged
-cms-edit peek <id> --id  # Look up by entry ID
+cms-edit peek --page-slug /pricing   # Show snapshot of /pricing; your active session is unchanged
+cms-edit peek --id <entryId>         # Look up by entry ID
 ```
 
 ## Batch Operations (run)
@@ -864,8 +873,8 @@ cms-edit sitemap --include page,article      # Include articles
 Use `--session <name>` or `CONTENTFUL_CMS_SESSION=<name>` to isolate parallel workflows.
 
 ```bash
-cms-edit --session agent-1 open /pricing
-cms-edit --session agent-2 open /blog
+cms-edit --session agent-1 open --page-slug /pricing
+cms-edit --session agent-2 open --article-slug /blog
 ```
 
 ## Related skills

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

@@ -10,7 +10,7 @@ Use this skill when creating or editing **navigation** entries and their items i
 ## Workflow
 
 1. **Create** a navigation: `cms-edit create navigation --label 'Main menu'`
-2. **Open** the nav: `cms-edit nav open <slug-or-id>` (or after create, use the printed open command)
+2. **Open** the nav: `cms-edit nav open --nav-name "Main menu"` or `cms-edit nav open --nav-id <id>` (printed after create/clone)
 3. **Add items** (new or existing):
    ```bash
    # Create a new nav item with a page link
@@ -48,7 +48,7 @@ This creates new copies of every NavigationItem and links them into the new navi
 In a navigation session, the root navigation entry is **`@c0`** (or the universal alias **`@root`**). The `@p0` alias only works in page/article sessions.
 
 ```bash
-cms-edit nav open main-navigation
+cms-edit nav open --nav-name "Main menu"
 cms-edit snapshot          # root is @c0; items are @c1, @c2, …
 cms-edit read @root        # same as @c0
 ```
@@ -73,7 +73,7 @@ cms-edit set @c0 visual <media-entry-id> --link
 Navigation entries are often linked from templates as **menu** or **footer**:
 
 ```bash
-cms-edit open <template-id> --id
+cms-edit open --id <template-id>
 cms-edit set @root menu <nav-entry-id> --link
 cms-edit set @root footer <footer-nav-id> --link
 cms-edit save

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

@@ -42,7 +42,8 @@ Create JSON-LD templates using these standard Mustache variables:
 - `{{slug}}` — page slug
 - `{{publishDate}}` — article publish date
 - `{{updatedAt}}` — last modification date
-- `{{authorName}}` — article author name
+- `{{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

package/skills/contentful-cms-seo-descriptions/SKILL.md

@@ -19,7 +19,7 @@ If no brand context is available, ask the user about their brand voice and targe
 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 /<slug>`
+      - `cms-edit open --page-slug /<slug>` (or `--article-slug` for articles)
       - `cms-edit read @page seoDescription` (or `read @page` for all fields)
    c. **Analyse** the page — primary purpose, problem it solves, desired user action
    d. **Generate** a meta description following the guidelines below

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

@@ -0,0 +1,132 @@
+---
+name: contentful-cms-sync-schema
+description: "Audit Contentful schema drift vs golden export, write descriptive diff reports, and build migration runbooks. Use when syncing a customer space to core schema or before running scripts/migrations."
+---
+
+# Sync Contentful schema to core
+
+Use when a customer Contentful space should match the **structural** core schema (content types, fields, non-enum validations). Do **not** use for full enum alignment of `componentType` / `collectionType` — each site keeps its own component names.
+
+## Golden reference
+
+| Artifact | Purpose |
+|----------|---------|
+| `docs/schema-export.json` | Structural golden (Pedestal `h4s3ip99qawo` / `master`) |
+| `docs/blank-schema.json` | New-project **bootstrap only** — not the sync target |
+
+Refresh golden:
+
+```bash
+contentful space export \
+  --space-id h4s3ip99qawo \
+  --environment-id master \
+  --management-token "$CONTENTFUL_MANAGEMENT_TOKEN" \
+  --skip-content --skip-webhooks --skip-roles --skip-tags \
+  --content-file docs/schema-export.json
+```
+
+## Workflow
+
+### 1. Resolve target space
+
+From the app’s `.env.local`:
+
+- `CONTENTFUL_SPACE_ID`
+- `CONTENTFUL_ENVIRONMENT_NAME` (or `CONTENTFUL_ENVIRONMENT`)
+
+Use `CONTENTFUL_MANAGEMENT_TOKEN` from the environment (global).
+
+### 2. Export target schema
+
+```bash
+contentful space export \
+  --space-id "$CONTENTFUL_SPACE_ID" \
+  --environment-id "$CONTENTFUL_ENVIRONMENT_NAME" \
+  --management-token "$CONTENTFUL_MANAGEMENT_TOKEN" \
+  --skip-content --skip-webhooks --skip-roles --skip-tags \
+  --content-file docs/schema-audit/<site>.json
+```
+
+### 3. Mechanical compare
+
+```bash
+node scripts/compare-contentful-schema.mjs \
+  --golden docs/schema-export.json \
+  --target docs/schema-audit/<site>.json \
+  --out docs/schema-audit/<site>-diff.json \
+  --summary docs/schema-audit/<site>-summary.md
+```
+
+Read `<site>-diff.json`. Enum-only diffs on `componentType`, `collectionType`, `externalComponentType` are **informational**.
+
+### 4. Write descriptive report
+
+Create or update **`docs/schema-audit/<site>.md`** with:
+
+1. **Summary** — space id, environment, counts; what is safe to auto-migrate vs needs review.
+2. **Missing content types** — purpose, editor impact, migration script.
+3. **Missing fields** — per field: type, why golden has it (use `scripts/schema-descriptions-data.js`, `specs/CONTENT_MODEL.md`), suggested migration from `scripts/migrations/`.
+4. **Extra types/fields** — site-specific; **keep** unless product says remove (e.g. Brightline analytics fields).
+5. **Field mismatches** — non-enum differences (colour palettes, RTF validations). Usually **optional** alignment; do not block structural migrations.
+6. **Migration runbook** — ordered list with dry-run commands (see below).
+7. **Post-migration checks** — re-export, re-compare, `pnpm generate:types`, `cms-edit schema component`.
+
+### 5. Apply migrations (human approval)
+
+**Never** `contentful space import` a full export onto a live space with content (webhook 409s, enum risk). Use **`contentful space migration`** only.
+
+Standard order when diff shows these gaps:
+
+| Order | Script | Adds |
+|-------|--------|------|
+| 1 | `12-add-html-component.js` | `htmlComponent` content type + array link validations |
+| 2 | `13-add-tag-type-fields.js` | TagType index page fields (includes `htmlComponent` in topContent) |
+| 2b | `13-add-tag-type-fields-no-html.js` | Same as 13 **without** `htmlComponent` in topContent — use for Brightline / BLK while htmlComponent is WIP |
+| 3 | `14-add-tag-show-field.js` | `show` on tag / tagType |
+| 4 | `16-add-navigation-item-long-text.js` | `navigationItem.longText` |
+| 5 | `15-add-slug-regexp-validation.js` | Slug format validation |
+| 6 | `17-add-article-authors.js` | `article.authors` array + backfill from `author` |
+
+Site-specific (run only when diff shows missing field **and** app uses it):
+
+| Script | Scope |
+|--------|--------|
+| `02-add-breadcrumb-title.js` | breadcrumbTitle on page/article/tag/custom |
+| `05-add-phone-number-brightline.js` | **Brightline spaces only** |
+| `06-add-tracking-event-name-brightline.js` | **Brightline spaces only** |
+| `03`–`11`, `07`–`10` | External component / link extensions — check diff |
+
+Gaps with **no** script (e.g. `navigationItem.longText`, `media.gradient` on Pedestal): flag in report; add `scripts/migrations/16+` before applying if required.
+
+Dry-run:
+
+```bash
+contentful space migration \
+  --space-id "$CONTENTFUL_SPACE_ID" \
+  --environment-id "$CONTENTFUL_ENVIRONMENT_NAME" \
+  --management-token "$CONTENTFUL_MANAGEMENT_TOKEN" \
+  scripts/migrations/12-add-html-component.js
+```
+
+Remove dry-run flags only after reviewing output. Re-run compare until **missing types/fields** are cleared (extras and enum diffs may remain).
+
+### 6. App follow-up
+
+In the customer app directory:
+
+```bash
+pnpm generate:types
+pnpm type-check
+```
+
+## Safety rules
+
+- Do **not** shrink `componentType` / `collectionType` `in` lists on live spaces.
+- Migration **15** does not fix existing invalid slug **entries** — editors must fix on save.
+- Legacy media spaces (separate `video` / `illustration` types instead of `media`) need a **separate** consolidation project — not this skill’s default scope.
+
+## Related docs
+
+- `docs/DEVELOPMENT.md` — Contentful migrations section
+- `docs/schema-audit/README.md` — artifact layout
+- `site-workflows-project-cleanup` skill — `clean-schema` for **new** empty spaces only

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

@@ -11,7 +11,7 @@ Use this skill when creating or editing **templates** (layout shells with preCon
 
 1. **Create** a template: `cms-edit create template --label 'Campaign Landing'`
 2. **List** templates: `cms-edit list --type template`
-3. **Open** by ID: `cms-edit open <template-id> --id`
+3. **Open** by cmsLabel or ID: `cms-edit open --template-label "Default"` or `cms-edit open --id <template-id>`
 4. Edit content: set **preContent** and **postContent** (content arrays) via session snapshot refs; use `add`, `set`, `remove`, `move` as for pages. Set **menu** and **footer** (single navigation links) with `cms-edit set @ref menu <nav-entry-id> --link` and same for `footer`.
 5. Set **colours**: `cms-edit set @ref backgroundColour Navy`, `cms-edit set @ref textColour White` (or project colour names).
 6. **Save**: `cms-edit save`