@se-studio/skills 1.0.39 → 1.0.40

package/CHANGELOG.md

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

package/package.json

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

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-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