@se-studio/skills 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @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
+
+- Bulk version bump: patch for all packages
+
+## 1.1.2
+
+### Patch Changes
+
+- Exclude redirect sources from sitemaps + robust protection against self and circular redirects.
+
+  - `buildRedirectMap` now normalizes internal paths (leading + trailing `/` to match urlCalculators + sitemap conventions) and reliably drops self-redirects (A → A). It also detects longer redirect cycles (A → B → A, etc.), drops the participating `from` rules from the baked map, and emits a `console.warn` during construction (visible in build/generate scripts).
+  - New exported utility: `filterSitemapEntriesExcludingRedirects(entries, redirectMap)`. Works on any `{ url: string }[]` (SitemapEntry, ISitemapEntry, etc.).
+  - The standard marketing site sitemap helper now accepts an optional `redirectMap` in `getSitemapEntries({ includeUnindexed, redirectMap })`. When provided, any URL that is the source of an active redirect is excluded from the generated sitemap entries. This is the recommended way to keep sitemaps clean when using editor-managed redirects.
+  - Widened the public `getSitemapEntries` option type in app helpers (additive; existing callers unaffected).
+  - Updated example app sitemaps (main + unindexed) to demonstrate fetching the map and passing it.
+  - Skill docs (`se-marketing-sites-redirects`) now include a "Redirects and sitemaps" section with usage patterns + notes on the improved cycle/self protection. Also updated routing docs.
+  - `buildRedirectMap` / `RedirectMap` / `getRedirectMap` behaviour for the middleware baked map is now safer (no self-loops or cycles will be baked).
+
+  Consumers using the `marketingSiteSitemap` helper + `getRedirectMap` at build time can now easily exclude redirect sources from both their static redirect map (for middleware) and their sitemaps in one consistent way.
+
+  See the redirect skill for the full recommended build-time pattern and the new filter helper.
+
 ## 1.1.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.1.1",
+  "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-redirects/SKILL.md

@@ -60,7 +60,7 @@ The following are already in the packages:
 
 - `IRedirect` + `isRedirect` in `@se-studio/core-data-types` (now uses `fromInternal` / `toInternal`)
 - `baseRedirectConverter` + `BaseRedirectSkeleton`
-- `contentfulRedirectsRest` + `buildRedirectMap` + `getRedirectsWithErrors` / `getRedirectMap` (via `createAppHelpers`)
+- `contentfulRedirectsRest` + `buildRedirectMap` (now with robust self/cycle guards + normalization) + `getRedirectsWithErrors` / `getRedirectMap` (via `createAppHelpers`)
 - Revalidation tag `redirect` (so the existing webhook machinery knows about the new type)
 
 You only need to wire the **rebuild** side in your app.
@@ -174,6 +174,30 @@ export const config = {
 
 If you already have a `middleware.ts` for A/B or other things, just add the redirect check at the very top (before any other logic).
 
+### 4.2.1 Redirects and sitemaps
+
+When you create a redirect whose `from` (raw or resolved via internal picker) matches a URL that would otherwise be listed in your sitemap, that URL should generally be omitted from the sitemap (search engines should not be told to crawl a source that 301s away).
+
+The shared libraries now support this easily:
+
+- The `getSitemapEntries(...)` function returned by the marketing sitemap helper (when you configure `marketingSiteSitemap` in `createAppHelpers`) accepts an optional `redirectMap` in its options. When supplied, any entry whose URL is a redirect source is filtered out before the entries are returned to `buildSitemap`.
+- Standalone: `filterSitemapEntriesExcludingRedirects(entries, redirectMap)` (exported from `@se-studio/contentful-rest-api`) works on any `{ url: string }[]` list for custom flows.
+
+Recommended pattern (in `app/sitemap.ts` and the unindexed route):
+
+```ts
+import { getRedirectMap, getSitemapEntries } from '@/lib/cms-server';
+import { buildSitemap } from '@se-studio/core-ui';
+
+export default async function sitemap() {
+  const redirectMap = await getRedirectMap({});
+  const entries = await getSitemapEntries({ includeUnindexed: false, redirectMap });
+  return buildSitemap([() => Promise.resolve(entries)], { baseUrl, ... });
+}
+```
+
+Pure `fromPath` vanity redirects were already absent from sitemaps (no backing content entry). This mainly helps when you redirect *away from* live CMS pages/articles.
+
 ### 4.3 Webhook = Deploy Hook (the trigger)
 
 In Contentful → Settings → Webhooks, create (or reuse) a webhook that fires on:
@@ -226,6 +250,8 @@ Then commit the updated `.agents/skills/...` (the monorepo keeps them in sync wi
 
 The `redirect` content type and the `buildRedirectMap` / `getRedirectMap` helpers are intentionally stable so a future faster path can consume the same data.
 
+`buildRedirectMap` automatically drops self-redirects (A → A after normalization) and any rules that participate in longer cycles, emitting a console warning for cycles during build/generate. Internal paths are normalized with a trailing `/` to match your urlCalculators and sitemap hrefs.
+
 ---
 
 **You now have editor-managed redirects that are as robust and low-surprise as your A/B tests, using only patterns that already exist in the codebase.**

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