@se-studio/skills 1.3.4 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.4.1
+
+### Patch Changes
+
+- f2de9ba: Document CMS smoke integrity (`cmsIntegrity`, `runStaticSmokeTestWithIntegrity`), Vercel `VERCEL_FORCE_NO_BUILD_CACHE`, and update `se-marketing-sites-smoke-test-setup` skill plus `example-empty` reference.
+
+## 1.4.0
+
+### Minor Changes
+
+- Bulk version bump: minor for all packages
+
 ## 1.3.4
 
 ### Patch Changes

package/package.json

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

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

@@ -27,12 +27,11 @@ Run after any of these change:
 
 | Action | Automatic on git push? |
 |--------|------------------------|
-| Copy **committed** `editor-pack/` + `.mcpb` into cms-edit-host | Yes (`stage-site.mjs` on Vercel build) |
+| Copy **committed** `editor-pack/` into cms-edit-host | Yes (`cms-edit host stage` via `stage-site.mjs` on Vercel build) |
 | Run `editor-pack generate` | **No** — always manual (this skill) |
-| Rebuild `.mcpb` on Vercel | **No** — commit locally (`pnpm cms-edit:mcpb` or `build-mcpb.sh`) when `hosted.mcpUrl` or extension metadata changes |
 | 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.
+Editors do **not** reconnect Claude Integrations when only the editor pack changes.
 
 **Staging:** `stage-site.mjs` copies committed artifacts into `cms-edit/host/` before build. Requires `CMS_EDIT_ROOT` on Vercel. Single-site repos default to `cms-edit` locally; multi-site repos need `CMS_EDIT_ROOT` in `cms-edit/host/.env.local`. Run manually with `pnpm cms-edit:stage` (or site-specific variant).
 
@@ -88,13 +87,13 @@ git commit -m "chore(cms-edit): regenerate editor pack"
 
 ### Customer repo with `cms-edit/host/` (SE Studio, Pedestal, Headwater)
 
-Commit `editor-pack/` (and `.mcpb` if `hosted.mcpUrl` changed), then push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger a host rebuild (`stage-site.mjs` copies committed artifacts).
+Commit `editor-pack/`, then push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger a host rebuild (`stage-site.mjs` copies committed artifacts).
 
 ```bash
 git push
 ```
 
-Manual deploy without pushing: `pnpm cms-edit:deploy` (single-site) or `pnpm cms-edit:deploy:<site>` (multi-site) — runs validate, stage, then `vercel deploy --prod`.
+Manual deploy without pushing: `pnpm cms-edit:deploy` (single-site) or `pnpm cms-edit:deploy:<site>` (multi-site) — runs validate, stage, then `vercel deploy --prod` **from the repo root** with `--project <vercel-project>`. Do not `cd cms-edit/host` first (Vercel Root Directory is already `cms-edit/host`).
 
 ### Customers without `cms-edit/host/` in their repo
 
@@ -114,10 +113,10 @@ SE Studio sites store the marketing homepage as Contentful slug **`index`** (pub
 ## Verify after deploy
 
 ```bash
-curl -s -H "Authorization: Bearer <PAT>" "https://<host>/api/health" | jq .gettingStarted
+curl -s "https://<host>/api/health" | jq
 ```
 
-In Claude Desktop (hosted extension): ask to read `cms-edit://customer/routing` and confirm new component types appear in `cms-edit://customer/components-index`.
+In Claude Desktop (hosted integration): ask to read `cms-edit://customer/routing` and confirm new component types appear in `cms-edit://customer/components-index`.
 
 ## Related docs
 
@@ -133,4 +132,4 @@ In Claude Desktop (hosted extension): ask to read `cms-edit://customer/routing`
 |------------|-------|
 | Guidelines changed | `contentful-cms-update-cms-guidelines` |
 | New registration | `se-marketing-sites-register-cms-features` |
-| Editor `.mcpb` install | `contentful-cms-setup` (hosted path) |
+| Editor Integrations setup | `contentful-cms-setup` (hosted path) |

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

@@ -11,35 +11,32 @@ Use this skill when the user wants to install or configure the `cms-edit` MCP se
 
 | Path | When to use |
 |------|-------------|
-| **Hosted (`.mcpb`)** | User is a content editor; SE sent a `.mcpb` file; no Node.js |
+| **Hosted (Integrations)** | Content editor; SE sent an onboarding URL (e.g. `/cms-edit`); no Node.js |
 | **Local (setup wizard)** | Developer; multi-space; or no hosted deployment |
 
 Ask which applies if unclear.
 
 ---
 
-## Hosted setup (`.mcpb` extension)
+## Hosted setup (Claude Integrations + OAuth)
 
-Use when the user has a **`.mcpb` file** from SE (e.g. `cms-edit-om1.mcpb`). Do **not** run the setup wizard.
+Use when SE sent an **onboarding link** (e.g. `https://your-site.content.se.studio/cms-edit`). Do **not** run the setup wizard.
 
-### Step 1: Get a Contentful token
+### Step 1: Connect to Claude
 
-Same as local — tell the user to create a **personal access token** in Contentful (Settings → CMA tokens), name it `Claude Desktop`, and copy it.
+1. Open the link SE sent (or **Connect to Claude** on `/cms-edit`)
+2. Confirm the connector in Claude Desktop or claude.ai
+3. Sign in with **Contentful** when prompted (same account SE invited to the space)
 
-### Step 2: Install the extension
-
-1. Open [Claude Desktop](https://claude.ai/download)
-2. **Settings → Extensions → Install Extension…** (or double-click the `.mcpb` file)
-3. Paste the Contentful token when prompted
-4. Fully quit and reopen Claude Desktop
+Manual alternative: Claude → **Customize → Connectors** → Add custom connector → paste the MCP URL (`…/api/mcp`) → Connect.
 
 Full editor guide: `packages/contentful-cms/HOSTED.md`
 
-### Step 3: Verify
+### Step 2: Verify
 
-In Claude, ask to list pages or open the homepage. If `cms_edit` returns content, setup is complete.
+In Claude, ask to read the cms-edit guide or verify the connection. If `cms_edit` returns content, setup is complete.
 
-**Token update:** Settings → Extensions → open the cms-edit extension → update token.
+**Reconnect:** Settings → Integrations → Connect again if the connection stops working.
 
 ---
 
@@ -126,4 +123,4 @@ If it returns a page structure, setup is complete. If it errors, see Troubleshoo
 It should contain an `mcpServers.cms-edit` entry. If missing, run the wizard again.
 
 **Adding another space**
-→ Run `npx @se-studio/contentful-cms@latest setup` again — it merges the new space into the existing config.
+→ Run `npx @se-studio/contentful-cms@latest setup` again — it merges the new space into the existing config.

package/skills/se-marketing-sites-create-page/SKILL.md

@@ -121,16 +121,23 @@ If a route needs a different layout (e.g. no header/footer), create `layout.tsx`
 
 ## A/B Test Variant Route (`page-test`)
 
-When A/B testing is enabled, variant pages are served through a `/page-test/[...slugs]` route that the middleware rewrites to. This route **must** use `generatePageTestMetadata` (not `generatePageMetadata`) so that `robots`/`indexed` comes from the **canonical/control** page — variant entries are intentionally `indexed: false` in Contentful.
+When A/B testing is enabled, variant pages are served through a `/page-test/[...slugs]` route that the middleware rewrites to. This route **must** use:
+
+- **`generatePageTestMetadata`** (not `generatePageMetadata`) so that `robots`/`indexed` comes from the **canonical/control** page — variant entries are intentionally `indexed: false` in Contentful.
+- **`generatePageTest`** (not `generatePage`) so breadcrumbs, `model.href`, and JSON-LD use the **control/canonical** path while variant **content** still renders.
+
+`BasicLayout` should resolve breadcrumbs and structured data from `currentPath ?? model.href` (the factory passes `currentPath={canonicalPath}`).
 
 If the slug is not a known variant in `testsByPath`, **return 404** (`notFound()`): there is no control page to merge, and `/page-test/…` is only valid for configured tests.
 
+Direct visits to a variant's own CMS URL (normal `[...slugs]` route) continue to use `generatePage` and show variant breadcrumbs.
+
 ```typescript
 import { findCanonicalPath } from '@se-studio/ab-testing';
 import type { ResolvingMetadata } from 'next';
 import { notFound } from 'next/navigation';
 import { testsByPath } from '@/generated/abTests';
-import { generatePage, generatePageTestMetadata } from '@/lib/route-handlers';
+import { generatePageTest, generatePageTestMetadata } from '@/lib/route-handlers';
 import { getPageRouteConfig } from '@/lib/routeConfig';
 
 /** Variant slug must appear in testsByPath; otherwise this route is not valid. */
@@ -165,13 +172,15 @@ export async function generateMetadata(
 }
 
 export default async function (props: PageProps<'/page-test/[...slugs]'>) {
-  const { slug, path } = await extractDetails(props);
-  requireCanonicalPath(slug);
-  return generatePage(slug, path, getPageRouteConfig(slug));
+  const { slug } = await extractDetails(props);
+  const canonicalPath = requireCanonicalPath(slug);
+  const canonicalSlug = canonicalPath.replace(/^\/|\/$/g, '') || slug;
+  // Use generatePageTest: variant contents with control identity (href, breadcrumbs, JSON-LD).
+  return generatePageTest(slug, canonicalSlug, canonicalPath, getPageRouteConfig(canonicalSlug));
 }
 ```
 
-Also export `generatePageTestMetadata` from the app's `src/lib/route-handlers.ts` destructuring alongside `generatePageMetadata`.
+Also export `generatePageTestMetadata` and `generatePageTest` from the app's `src/lib/route-handlers.ts` destructuring alongside `generatePageMetadata`.
 
 ## See Also
 

package/skills/se-marketing-sites-redirects/SKILL.md

@@ -22,12 +22,17 @@ The repo contains the official migration:
 
 ```bash
 # Create the redirect content type (clean fromPath + fromInternal / toPath + toInternal model)
-node scripts/migrations/18-create-redirect-content-type.js
+contentful space migration ... scripts/migrations/18-create-redirect-content-type.js
+
+# If the redirect CT already exists but lacks field defaults (statusCode → 301, active → true):
+contentful space migration ... scripts/migrations/22-set-redirect-field-defaults.js
 ```
 
-Run it with the Contentful CLI (or the contentful-cms package tools) and the usual `CONTENTFUL_SPACE_ID` + `CONTENTFUL_MANAGEMENT_TOKEN` + environment.
+Run with the Contentful CLI (or the contentful-cms package tools) and the usual `CONTENTFUL_SPACE_ID` + `CONTENTFUL_MANAGEMENT_TOKEN` + environment.
+
+If you previously created a Redirect CT using an older multi-field version of the migration, **delete the "Redirect" content type first**, then re-run migration 18 to get the clean single-ref model.
 
-If you previously created a Redirect CT using an older multi-field version of the migration, **delete the "Redirect" content type first**, then re-run to get the clean single-ref model.
+Migration 22 only updates the content type definition (editor defaults for **new** entries). It does not backfill existing redirect entries.
 
 After running you will have a new (or repaired) content type called **Redirect**.
 
@@ -44,8 +49,8 @@ Key fields (all documented with help text in the migration):
 - `toInternal` (single reference picker, same allowed types as fromInternal)
 
 **Other**
-- `statusCode` — dropdown: 301 (permanent — recommended), 302, 307, 308.
-- `active` — boolean (default on). Turn off to disable a rule without deleting it.
+- `statusCode` — dropdown: 301 (permanent — recommended), 302, 307, 308. **Defaults to 301** in the editor for new entries.
+- `active` — boolean. **Defaults to true** for new entries. Turn off to disable a rule without deleting it.
 - `note` — internal editor note (never shown on the site).
 - `cmsLabel` — required internal label.
 
@@ -200,15 +205,29 @@ Pure `fromPath` vanity redirects were already absent from sitemaps (no backing c
 
 ### 4.3 Webhook = Deploy Hook (the trigger)
 
-In Contentful → Settings → Webhooks, create (or reuse) a webhook that fires on:
+Baked redirects require a **rebuild**, not ISR revalidation. Use a Contentful webhook that calls your **Vercel Deploy Hook** URL (not `/api/revalidate`).
+
+**Automated setup (recommended):**
 
-- Entry publish / unpublish / delete for content type `redirect`
+1. In Vercel → Project → Settings → **Deploy Hooks**, create a hook for Production (and optionally Preview). Copy each URL.
+2. Add to `.env.local`:
+   ```bash
+   VERCEL_DEPLOY_HOOK_URL=https://api.vercel.com/v1/integrations/deploy/...
+   # optional:
+   VERCEL_PREVIEW_DEPLOY_HOOK_URL=https://api.vercel.com/v1/integrations/deploy/...
+   VERCEL_PROTECTION_BYPASS_TOKEN=...   # only if you need the bypass header on hook calls
+   ```
+3. From the app directory (requires `CONTENTFUL_MANAGEMENT_TOKEN` + `CONTENTFUL_SPACE_ID`):
+   ```bash
+   pnpm setup:redirect-deploy-hook
+   ```
+   This creates/replaces Contentful webhooks named `Vercel Deploy Hook (Redirects)` (and `… – Preview` when the preview URL is set). They fire on **Entry publish / unpublish / delete** filtered to content type `redirect`.
 
-Point the URL at your **Vercel Deploy Hook** (Project → Settings → Deploy Hooks → create one for Production and optionally for Preview).
+The script lives at [`scripts/setup-redirect-deploy-hook.ts`](../../../../scripts/setup-redirect-deploy-hook.ts) in the monorepo; `example-empty` wires it via `package.json`.
 
-Add the usual headers your deploys need (`x-vercel-protection-bypass` if you use deployment protection, `REVALIDATION_SECRET` if you also want the normal reval to run, etc.).
+**Manual setup:** same triggers and filter (`redirect` only), POST to the deploy hook URL. Do **not** point this at `/api/revalidate` — that only invalidates cache tags and will not regenerate `src/generated/redirects.ts`.
 
-That's it. Publish a redirect → Vercel starts a build → the generate step runs → the new static map is in the bundle → redirects work.
+That's it. Publish a redirect → Vercel starts a build → `prebuild` runs `generate:redirects` → the new static map is in the bundle → redirects work.
 
 ## 5. Testing
 

package/skills/se-marketing-sites-smoke-test-setup/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: se-marketing-sites-smoke-test-setup
+description: "Set up or regenerate smoke.cases.json for local smoke tests from the production sitemap. Use when adding smoke tests, refreshing smoke URLs after route or content changes, or migrating off smoke.config.ts."
+---
+
+# Smoke test setup (static `smoke.cases.json`)
+
+Local smoke tests use curated HTTP cases in **`smoke.cases.json`**. Optionally enable **`cmsIntegrity`** for a local-only Contentful article-link check (no `cms-server` import in smoke scripts).
+
+Requires `@se-studio/site-check` **^2.6.1** when using `cmsIntegrity` or `pnpm smoke-test` with integrity enabled; **2.1.2+** for cache log audit; **2.0.0+** for HTTP-only static smoke.
+
+Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smoke failure. **Deployment / live smoke stays HTTP-only** — do not enable `cmsIntegrity` on Vercel deployment checks.
+
+## Prerequisites
+
+- App has `scripts/smoke-test-run.ts` (see [CMS article-link integrity](#cms-article-link-integrity-optional) below).
+- `package.json`: `"smoke-test:run": "tsx scripts/smoke-test-run.ts"`.
+- `SITEMAP_PROD_URL` in `.env.example` (production sitemap for URL curation).
+- When `cmsIntegrity.enabled` is true: `@se-studio/contentful-rest-api@^1.10.0`, `@se-studio/core-data-types@^1.5.1`, Contentful tokens in `.env.local`.
+
+## Script matrix
+
+| Script | Purpose |
+|--------|---------|
+| `pnpm smoke-test` | Start dev server + functional smoke (default) |
+| `pnpm smoke-test:run` | Smoke only (server already up) |
+| `pnpm smoke-test:preview` | Smoke against Vercel preview (`runPreviewStaticSmokeTest`; no local server) |
+| `pnpm smoke-test:audit` | Functional smoke + server log cache audit |
+| `pnpm smoke-test:cache` | `build` + `start` + double-pass `x-nextjs-cache` verify |
+| `pnpm smoke-test:deploy-check` | Post-build gate: `start` (no rebuild) + functional smoke — use in Vercel `buildCommand` |
+| `pnpm smoke-test:live` | Live deployment URL smoke — GitHub Action + Vercel Deployment Checks |
+
+Example `package.json` entries:
+
+```json
+"smoke-test": "smoke-test-one 3012",
+"smoke-test:run": "tsx scripts/smoke-test-run.ts",
+"smoke-test:preview": "bash -c 'set -a && [ -f .env.local ] && . ./.env.local; set +a && exec tsx scripts/smoke-test-preview.ts'",
+"smoke-test:audit": "SMOKE_TEST_AUDIT_CACHE_LOGS=true smoke-test-one 3012",
+"smoke-test:cache": "SMOKE_TEST_SERVER_SCRIPT=start SMOKE_TEST_VERIFY_CACHE=true smoke-test-one 3012",
+"smoke-test:deploy-check": "smoke-test-deploy-check",
+"smoke-test:live": "smoke-test-live"
+```
+
+**Vercel build gate** — append to root `vercel.json` so failed smoke fails the build before deploy:
+
+```json
+{
+  "buildCommand": "pnpm build && pnpm smoke-test:deploy-check"
+}
+```
+
+**Vercel Deployment Check (live URL)** — GitHub Action on `vercel.deployment.ready` tests `client_payload.url` before production domains alias. Workflow must live on the repo **default branch**. Register the status `name` in Vercel → Settings → Build and Deployment → Deployment Checks.
+
+Filter on `client_payload.environment == 'production'` when Deployment Checks target production only. Vercel also dispatches for preview and custom environments (`preview`, `develop`, etc.); skip those to avoid duplicate CI runs. Use `workflow_dispatch` without an environment filter for manual smoke against any URL.
+
+```yaml
+# .github/workflows/deployment-smoke.yml
+name: Deployment smoke
+
+on:
+  repository_dispatch:
+    types:
+      - vercel.deployment.ready
+
+jobs:
+  smoke:
+    if: |
+      github.event.client_payload.project.name == '<vercel-project-name>' &&
+      github.event.client_payload.environment == 'production'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: vercel/repository-dispatch/actions/checkout@v1
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Live deployment smoke
+        env:
+          DEPLOYMENT_URL: ${{ github.event.client_payload.url }}
+          VERCEL_PROTECTION_BYPASS_TOKEN: ${{ secrets.VERCEL_PROTECTION_BYPASS_TOKEN }}
+        run: pnpm smoke-test:live
+      - name: Report Deployment Check status
+        if: always()
+        uses: vercel/repository-dispatch/actions/status@v1
+        with:
+          name: "Vercel - <vercel-project-name>: deployment smoke"
+```
+
+GitHub secret: `VERCEL_PROTECTION_BYPASS_TOKEN` (Vercel → Deployment Protection → Protection Bypass for Automation). Set `SMOKE_TEST_IGNORE=true` to bypass smoke in an emergency.
+
+Or from the app directory without a per-app script: `node ../../scripts/smoke-test-preview.mjs` (loads `.env.local` and calls `runPreviewStaticSmokeTest`).
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `SITEMAP_PROD_URL` | Production site URL for sitemap fetch when curating `smoke.cases.json` |
+| `PREVIEW_SITE_URL` | Vercel develop/preview deployment URL for `smoke-test:preview` |
+| `DEPLOYMENT_URL` | Live deployment URL for `smoke-test:live` (CI / `repository_dispatch` payload) |
+| `VERCEL_PROTECTION_BYPASS_TOKEN` | Deployment Protection bypass secret (aliases: `VERCEL_AUTOMATION_BYPASS_SECRET`, `VERCEL_BYPASS_TOKEN`) |
+| `PRODUCTION_SITE_URL` | Optional canonical production URL for audits and related tooling |
+| `SMOKE_TEST_SKIP_INTEGRITY` | Set by `smoke-test-one` when integrity runs in parallel; HTTP-only child run |
+| `VERCEL_FORCE_NO_BUILD_CACHE` | **Vercel project env only** (`1`) — skip remote build cache when webpack `WasmHash` failures occur on Vercel (not `vercel.json`) |
+
+Add smoke-related vars to `.env.example` under an SEO / site-check section. `runPreviewStaticSmokeTest` requires `PREVIEW_SITE_URL` and a bypass token in `.env.local`.
+
+### Vercel build cache (`VERCEL_FORCE_NO_BUILD_CACHE`)
+
+Intermittent Vercel `next build` failures (`WasmHash._updateWithBuffer` / `Cannot read properties of undefined (reading 'length')`) often correlate with a stale remote build cache. Mitigation:
+
+```bash
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE preview develop --value 1 --yes
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE production --value 1 --yes
+```
+
+- Set on the **Vercel project** (Preview and/or Production). Not in app `.env.local`.
+- Tradeoff: cold builds ~1m vs ~30s cached.
+- Roll out to other marketing sites on the next Vercel config pass when builds fail intermittently locally pass.
+- Document in the app `AGENTS.md` when applied.
+
+## Workflow
+
+### 1. Confirm port
+
+Read `package.json` — e.g. `next dev -p 3012` → port **3012**.
+
+### 2. Fetch sitemap (production first)
+
+Use `SITEMAP_PROD_URL` from `.env.example`:
+
+```bash
+curl -sSL "$SITEMAP_PROD_URL"
+```
+
+Parse all `<loc>` URLs. Strip host; keep pathnames with trailing slashes as in sitemap.
+
+Use **local** sitemap only when verifying routes not yet on production:
+
+```bash
+curl -sS "http://localhost:<port>/sitemap.xml"
+```
+
+### 3. Understand route patterns
+
+Read (do not guess from constants alone):
+
+- `src/app/(cms-routes)/` — custom segments (e.g. se-website uses `/work/`, not `/articles/`).
+- `src/lib/constants.ts` — `ARTICLES_BASE`, feature flags, slugs.
+- Prior smoke output or `.md` probes for listing pages that do not export markdown.
+
+### 4. Bucket URLs into categories
+
+| Category | Typical paths | Samples |
+|----------|---------------|---------|
+| `home` | `/` | 1 |
+| `page` | Top-level CMS pages (not home, not article trees) | 2 |
+| `article-type-index` | e.g. `/work/`, `/blog/` | 1 |
+| `article` | Nested article/case-study URLs | 2 |
+| `tag` / `tags-index` | If in sitemap and enabled | 1–2 each |
+| `person` / `people-listing` | If in sitemap and enabled | 1–2 each |
+
+**Exclude** obvious non-prod slugs: `tmp-*`, draft pages, unless intentionally tested.
+
+Keep sets lean (6–10 cases). Avoid heavy paginated listing URLs unless needed for coverage.
+
+### 5. Set `expectMarkdown`
+
+- **true** — page and `.md` should return 200 with `text/markdown` (home, pages, articles).
+- **false** — listing shells that return 404 or “not supported” for `.md` (optional; omit markdown checks).
+
+Probe when unsure (local dev server):
+
+```bash
+curl -sI "http://localhost:<port>/some-path.md"
+```
+
+### 6. Write `smoke.cases.json`
+
+```json
+{
+  "siteName": "my-app",
+  "port": 3012,
+  "cases": [
+    { "category": "home", "label": "Home", "path": "/", "expectMarkdown": true },
+    { "category": "page", "label": "About", "path": "/about/", "expectMarkdown": true }
+  ]
+}
+```
+
+Optional `cmsIntegrity` (local only — see section below):
+
+```json
+{
+  "cmsIntegrity": {
+    "enabled": true,
+    "routing": {
+      "articleTypesBasePath": "/resources",
+      "tagsBasePath": "/topics",
+      "peopleBasePath": "/team",
+      "defaultTopic": "other",
+      "enablePrimaryTagPartOfSlug": true,
+      "topiclessArticleTypeSlugs": ["ebooks"]
+    }
+  }
+}
+```
+
+Map `routing` from `src/lib/constants.ts` (or the app’s URL rules). `enabled: false` omits the integrity fetch.
+
+- `path` — site-relative, trailing slash when the site uses trailing slashes.
+- `port` — default; override at run time with `SMOKE_TEST_PORT`.
+
+### 7. Verify
+
+```bash
+pnpm smoke-test:run    # HTTP (+ integrity when cmsIntegrity.enabled)
+pnpm smoke-test          # starts dev server; integrity runs in parallel when enabled
+```
+
+Expect `Summary: N cases, 0 failed`. With integrity: `article link integrity: ok`. Preview API / `DRAFT_ONLY` logs in dev are OK.
+
+Optional cache audit:
+
+```bash
+pnpm smoke-test:audit
+```
+
+Expect `cache log audit: ok` with no 2MB errors. `cache skip` lines are warnings by default.
+
+### 8. Commit
+
+Commit `smoke.cases.json`. Remove legacy `smoke.config.ts` if present.
+
+## CMS article-link integrity (optional)
+
+Local-only check: one Contentful fetch validates all article/person/tag link `href` values (broken links, conversion errors). Runs in parallel with server boot when using `pnpm smoke-test`.
+
+**`scripts/smoke-test-run.ts`:**
+
+```ts
+import {
+  formatCombinedSmokeReport,
+  getCombinedSmokeExitCode,
+  runStaticSmokeTestWithIntegrity,
+} from '@se-studio/site-check/smoke-test';
+
+async function main(): Promise<number> {
+  const skipIntegrity = (process.env.SMOKE_TEST_SKIP_INTEGRITY ?? '').toLowerCase() === 'true';
+  const { integrity, http } = await runStaticSmokeTestWithIntegrity('smoke.cases.json', {
+    skipIntegrity,
+  });
+  console.log(formatCombinedSmokeReport(integrity, http));
+  return getCombinedSmokeExitCode(integrity, http);
+}
+```
+
+Remove legacy `smoke-test:validate-links`, `smoke-test-preload.cjs`, and bespoke link-validation scripts when migrating.
+
+**Per-site rollout:** bump `@se-studio/site-check@^2.6.1`, add `cmsIntegrity` to `smoke.cases.json`, update `smoke-test-run.ts`, run `pnpm smoke-test` locally. Reference consumer: `om1-website` (`develop`).
+
+## Migrating from `smoke.config.ts`
+
+1. Delete `smoke.config.ts`.
+2. Simplify `smoke-test:run` script (no bash, no `NODE_OPTIONS`, no preload).
+3. Update `@se-studio/site-check` to `^2.6.1` when adopting integrity; otherwise `^2.1.2` minimum.
+4. Follow workflow above to create `smoke.cases.json`.
+
+## Reference
+
+- HTTP + integrity example: `apps/example-empty/smoke.cases.json` and `scripts/smoke-test-run.ts` (monorepo).
+- Package API: `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `auditCacheLogs` from `@se-studio/site-check/smoke-test`.
+- CMS integrity types: `@se-studio/site-check/cms-integrity`.

package/skills/site-workflows-contentful-vercel-setup/SKILL.md

@@ -399,16 +399,12 @@ Expected: `200 OK`. A `401` means the secret in the header doesn't match the dep
 
 ## (Optional) Redirects via the rebuild pattern
 
-If the project uses the `se-marketing-sites-redirects` skill, also configure a webhook that fires on the new `redirect` content type and points at a **Vercel Deploy Hook** (not a revalidation URL).
+If the project uses the `se-marketing-sites-redirects` skill, also wire redirect rebuild webhooks (separate from `/api/revalidate`):
 
-See `.agents/skills/se-marketing-sites-redirects/SKILL.md` (or the source in `packages/skills/skills/se-marketing-sites-redirects/SKILL.md`) for:
+1. Create Vercel Deploy Hook(s) (Production + optional Preview) and set `VERCEL_DEPLOY_HOOK_URL` (and optionally `VERCEL_PREVIEW_DEPLOY_HOOK_URL`) in `.env.local`.
+2. Run `pnpm setup:redirect-deploy-hook` from the app (monorepo script: `scripts/setup-redirect-deploy-hook.ts`).
 
-- Running the two official migration scripts (create the CT + later remove legacy `redirectTo` fields)
-- The exact content type fields + recommended help text
-- The build-time generate script + static middleware
-- Wiring the deploy hook webhook
+See `.agents/skills/se-marketing-sites-redirects/SKILL.md` for migrations, generate script, middleware, and full webhook details.
 
-This is deliberately the same "publish → deploy hook → build bakes static data" pattern used for A/B tests. It is the only supported path in v1 (Edge Config fast path is future work).
-
-You can have both the normal revalidation webhooks **and** the redirect deploy-hook webhook active at the same time.
+This is the same "publish → deploy hook → build bakes static data" pattern as A/B tests. You can run **both** ISR revalidation webhooks and redirect deploy-hook webhooks at the same time.
 - **To rotate the secret later**: re-run `scripts/setup-contentful-webhooks.ts` — it will generate a new secret and update everything automatically.