@se-studio/skills 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 1.2.0
+
+### Minor Changes
+
+- Add contentful-cms-regenerate-editor-pack skill for hosted MCP editor-pack workflow.
+
 ## 1.1.3
 
 ### Patch Changes

package/package.json

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

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

@@ -0,0 +1,136 @@
+---
+name: contentful-cms-regenerate-editor-pack
+description: "Regenerate cms-edit editor-pack for hosted MCP after registrations, guidelines, routing, or cms-editor docs change; validate, commit, and deploy."
+---
+
+# Regenerate cms-edit editor pack
+
+Use this skill when **site knowledge served to hosted cms-edit editors** must be refreshed. The editor pack becomes `cms-edit://customer/*` MCP resources on the hosted server.
+
+**Audience:** SE developers — not content editors.
+
+## When to regenerate
+
+Run after any of these change:
+
+| Change | Examples |
+|--------|----------|
+| CMS registrations | New component/collection in `src/lib/registrations.ts` |
+| Guidelines | `docs/cms-guidelines/**`, merged `COMPONENT_GUIDELINES_FOR_LLM.md` |
+| Routing / constants | `src/lib/constants.ts` (slugs, feature flags, `HOMEPAGE_SLUG`) |
+| Editor playbooks | `docs/cms-editor/**/*.md` |
+| Project config | `cms-edit/project.json` (`homepageSlug`, `devBaseUrl`, etc.) |
+
+**Also run** at the end of **`contentful-cms-update-cms-guidelines`** (`fresh` or `sync`) when guidelines changed.
+
+## What deploy does vs does not do
+
+| Action | Automatic on git push? |
+|--------|------------------------|
+| Copy **committed** `editor-pack/` into cms-edit-host | Yes (when `cms-edit/**` changes and Vercel builds) |
+| Run `editor-pack generate` | **No** — always manual (this skill) |
+| Rebuild `.mcpb` on Vercel | Yes (part of customer `vercel-build.sh`) |
+| Update hosted guide/prompts from `@se-studio/contentful-cms` | Redeploy host after bumping package version |
+
+Editors do **not** reinstall `.mcpb` when only the editor pack changes.
+
+## Step 1 — Locate config
+
+| Repo layout | Config path |
+|-------------|-------------|
+| Single-site (SE Studio) | `cms-edit/project.json` |
+| Multi-site monorepo | `cms-edit/<site>/project.json` |
+
+See `docs/CMS_EDIT_SETUP.md` for customer-specific paths.
+
+## Step 2 — Validate
+
+From repo root (requires `cms-edit` on PATH — `pnpm build` in se-core-product or `npx @se-studio/contentful-cms`):
+
+```bash
+cms-edit project validate --project-config <path-to-project.json>
+```
+
+## Step 3 — Generate
+
+**SE Studio (`se-website-2026`):**
+
+```bash
+pnpm cms-edit:editor-pack
+```
+
+**Generic / multi-site:**
+
+```bash
+cms-edit editor-pack generate --project-config cms-edit/<site>/project.json
+```
+
+Output: `cms-edit/editor-pack/` or `cms-edit/<site>/editor-pack/` (manifest, indexes, `routing.md`, `overview.md`, per-type guideline snippets).
+
+## Step 4 — Review diff
+
+Check at minimum:
+
+- `routing.md` — homepage CMS slug, article/tag paths
+- `components-index.json` / `collections-index.json` — new types present
+- `manifest.json` — resource list updated
+
+## Step 5 — Commit
+
+```bash
+git add cms-edit/editor-pack   # or cms-edit/<site>/editor-pack
+git commit -m "chore(cms-edit): regenerate editor pack"
+```
+
+## Step 6 — Deploy
+
+### SE Studio (git-connected Vercel)
+
+Push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger `cms-edit/scripts/vercel-build.sh`, which copies the committed pack and rebuilds the host.
+
+```bash
+git push
+```
+
+No `pnpm cms-edit:deploy` needed unless you want a manual Vercel deploy without pushing.
+
+### Other customers (e.g. Pedestal)
+
+From `se-core-product`:
+
+```bash
+./scripts/deploy-cms-edit-host.sh \
+  --config <customer-repo>/cms-edit/<site>/project.json \
+  --editor-pack <customer-repo>/cms-edit/<site>/editor-pack \
+  --prod
+```
+
+Or commit + push if that customer repo has its own cms-edit-host Vercel project.
+
+## Homepage slug reminder
+
+SE Studio sites store the marketing homepage as Contentful slug **`index`** (public URL `/`). Regenerated `routing.md` documents this. Set `website.homepageSlug` in `project.json` only for exceptions (e.g. Pedestal `home`).
+
+## Verify after deploy
+
+```bash
+curl -s -H "Authorization: Bearer <PAT>" "https://<host>/api/health" | jq .gettingStarted
+```
+
+In Claude Desktop (hosted extension): ask to read `cms-edit://customer/routing` and confirm new component types appear in `cms-edit://customer/components-index`.
+
+## Related docs
+
+| Doc | Purpose |
+|-----|---------|
+| `docs/CMS_EDIT_SETUP.md` | Full customer runbooks |
+| `packages/contentful-cms/docs/cms-edit-project-template/README.md` | `project.json` schema |
+| Customer `cms-edit/README.md` | Repo-specific scripts |
+
+## Sub-skill links
+
+| Prior work | Skill |
+|------------|-------|
+| Guidelines changed | `contentful-cms-update-cms-guidelines` |
+| New registration | `se-marketing-sites-register-cms-features` |
+| Editor `.mcpb` install | `contentful-cms-setup` (hosted path) |

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

@@ -0,0 +1,122 @@
+---
+name: contentful-cms-schema-audit
+description: "Run a comprehensive cross-site Contentful schema audit: field order, descriptions, validations, rich text embeds, field usage, webhooks, live preview, and Page Status. Use when comparing schemas across customer sites or recommending field reordering."
+---
+
+# Cross-site Contentful schema audit
+
+Use when you need a **comprehensive comparison** of Contentful schemas across all SE Studio marketing sites — not just drift vs golden.
+
+## Credentials
+
+Only **`CONTENTFUL_MANAGEMENT_TOKEN`** is required (global env var).
+
+- **Schema export** uses the Management API (CMA).
+- **Field usage** uses the Preview API; preview tokens are **resolved automatically** from each space's delivery API keys via CMA (same as `cms-edit index sync`). No per-site `.env.local` needed.
+
+The management token must have permission to read API keys for each target space.
+
+## Site registry
+
+Canonical site list: [`docs/schema-audit/sites.registry.json`](../../../docs/schema-audit/sites.registry.json)
+
+Customer-specific types/fields (excluded from core gap noise): [`docs/schema-audit/customer-overrides.registry.json`](../../../docs/schema-audit/customer-overrides.registry.json)
+
+## Two-phase workflow
+
+### Phase 1 — Scripts (factual)
+
+```bash
+export CONTENTFUL_MANAGEMENT_TOKEN=...
+
+# Full pipeline
+pnpm schema-audit
+
+# Subset of sites
+pnpm schema-audit -- --sites brightline,om1
+
+# Schema only (skip Preview API usage scan)
+pnpm schema-audit -- --skip-usage
+
+# Individual steps
+pnpm schema-audit:export
+pnpm schema-audit:space-config
+pnpm schema-audit:matrix
+pnpm schema-audit:rtf
+pnpm schema-audit:help-text
+pnpm schema-audit:usage
+pnpm schema-audit:insights
+pnpm schema-audit:sidebar
+pnpm schema-audit:report
+```
+
+Produces **`docs/schema-audit/REPORT.md`** — factual findings only.
+
+### Phase 2 — Analysis (interpretive)
+
+After Phase 1, read `REPORT.md` and matrix/usage JSON, then complete **`docs/schema-audit/ANALYSIS.md`**:
+
+1. Rank P0/P1/P2 actions (migrations vs editorial vs config)
+2. Decide which core gaps are intentional per-site
+3. Prioritize RTF violations that block editors or break renderers
+4. Batch help-text updates by content type
+5. Recommend deprecating or documenting never-used fields
+6. Confirm webhook URLs and live preview per deployment
+7. Plan Page Status sidebar installs (Ninetailed is PointMe-only)
+8. Extend `customer-overrides.registry.json` if new customer fields appear
+
+If `ANALYSIS.md` already exists, the report step writes a fresh template to `ANALYSIS.template.md` instead of overwriting.
+
+## Output artifacts
+
+| Path | Purpose |
+|------|---------|
+| `docs/schema-audit/exports/<site>.json` | Full CMA schema (content types + editor interfaces) |
+| `docs/schema-audit/exports/<site>-space-config.json` | Webhooks, live preview, Page Status install params |
+| `docs/schema-audit/matrix/*.json` | Cross-site matrices + classified gaps |
+| `docs/schema-audit/matrix/rtf-canonical-diff.json` | RTF violations vs `docs/schema-export.json` |
+| `docs/schema-audit/matrix/help-text-review.json` | Full core help-text review queue |
+| `docs/schema-audit/matrix/sidebar.json` | Sidebar widgets and Page Status gaps |
+| `docs/schema-audit/matrix/space-config.json` | Webhook summary per site |
+| `docs/schema-audit/usage/<site>.json` | Per-field population rates |
+| `docs/schema-audit/usage/never-used.json` | Never-used core fields |
+| `docs/schema-audit/usage/recommended-core-order.json` | Usage-ranked core editor order |
+| `docs/schema-audit/usage/site-additional-fields.json` | Per-site non-core fields (appendix) |
+| `docs/schema-audit/canonical/*.json` | Golden RTF rules and core field sets |
+| `docs/schema-audit/REPORT.md` | Phase 1 factual report |
+| `docs/schema-audit/ANALYSIS.md` | Phase 2 priorities (human/agent completed) |
+| `docs/schema-audit/report.json` | Machine-readable summary |
+
+## What the report covers
+
+1. **Core** content type and field gaps (customer-specific excluded via registry)
+2. Core validation/structural differences
+3. Rich text: violations vs codebase canonical (`docs/schema-export.json`) plus cross-site diffs
+4. Full help-text review queue for core fields
+5. Never-used core fields (0% population)
+6. Recommended core editor field order (usage-ranked; site extras in appendix)
+7. Webhooks, live preview, Page Status app (vs `docs/CONTENTFUL_WEBHOOK_REVALIDATION.md`)
+8. Sidebar placement gaps for Page Status on `component`/`collection`
+9. Cross-site usage medians and per-site profiles
+
+## Customer-specific scope
+
+PointMe (`nt_*`, `featureFlags`, pricing), Brightline phone/tracking fields, etc. are registered in **`customer-overrides.registry.json`**. They appear in the appendix, not core gap counts.
+
+Add new customer fields there before re-running so core gap noise stays low.
+
+## Enum fields
+
+`componentType`, `collectionType`, and `externalComponentType` enum lists are **informational** — each site keeps its own component names. See `matrix/enum-diffs.json`.
+
+## Migrations
+
+This skill is **read-only**. To align a space structurally, use **`contentful-cms-sync-schema`** after reviewing audit gaps in `ANALYSIS.md`.
+
+## Re-run after schema changes
+
+```bash
+pnpm schema-audit
+```
+
+Compare new `REPORT.md` / `matrix/*.json` to prior commit or regenerate descriptive site notes in `docs/schema-audit/<site>.md` if needed.

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

@@ -86,6 +86,7 @@ Standard order when diff shows these gaps:
 | 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` |
+| 7 | `21-add-article-bottom-content.js` | `article.bottomContent` array (idempotent; clones `content` link types) |
 
 Site-specific (run only when diff shows missing field **and** app uses it):
 

package/skills/contentful-cms-update-cms-guidelines/SKILL.md

@@ -324,6 +324,12 @@ All under `<appDir>`:
 
 ---
 
+## Hosted editor pack (after guidelines change)
+
+If the site uses **hosted cms-edit** (`cms-edit/` in the customer repo), regenerate and commit the editor pack so MCP resources pick up new guideline prose and component indexes. Vercel deploy copies the **committed** pack — it does not run `editor-pack generate` for you.
+
+Follow [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-regenerate-editor-pack/SKILL.md).
+
 ## Sub-skills reference
 
 | Purpose | Skill |
@@ -331,4 +337,5 @@ All under `<appDir>`:
 | Curate showcase mocks (Step 2 of `fresh`) | [`../se-marketing-sites-curate-showcase-mocks/SKILL.md`](../se-marketing-sites-curate-showcase-mocks/SKILL.md) |
 | Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | [`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md) |
 | Single-type regeneration (after code change) | [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md) (mode: single) |
+| Regenerate hosted editor pack | [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-regenerate-editor-pack/SKILL.md) |
 | Per-component pipeline detail | [`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md) |

package/skills/se-marketing-sites-register-cms-features/SKILL.md

@@ -89,3 +89,7 @@ Registering a component automatically adds it to the CMS Showcase (usually avail
 
 *   Ensure your `mock` object in the registration is complete and realistic.
 *   The showcase helps verify that `usedFields` and `UnusedChecker` are working correctly.
+
+## Hosted cms-edit
+
+If the site has `cms-edit/` (hosted MCP for editors), regenerate the editor pack after adding registrations so `cms-edit://customer/components-index` includes the new type. See [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-regenerate-editor-pack/SKILL.md).