@se-studio/skills 1.3.4 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @se-studio/skills
 
+## 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.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

@@ -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-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,211 @@
+---
+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 are **HTTP-only**: no `cms-server`, Contentful, or preload. Each app commits **`smoke.cases.json`** with curated URLs. Regenerate this file when routes or indexed content change materially.
+
+Requires `@se-studio/site-check` **2.1.2+** for cache log audit; **2.0.0+** for static smoke.
+
+Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smoke failure.
+
+## Prerequisites
+
+- App has `scripts/smoke-test-run.ts` calling `runStaticSmokeTest('smoke.cases.json')`.
+- `package.json`: `"smoke-test:run": "tsx scripts/smoke-test-run.ts"`.
+- `SITEMAP_PROD_URL` in `.env.example` (production sitemap for URL curation).
+
+## 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 |
+
+Add these to `.env.example` under an SEO / site-check section. `runPreviewStaticSmokeTest` requires `PREVIEW_SITE_URL` and a bypass token in `.env.local`.
+
+## 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 }
+  ]
+}
+```
+
+- `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
+```
+
+Expect `Summary: N cases, 0 failed`. 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.
+
+## 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.1.2`.
+4. Follow workflow above to create `smoke.cases.json`.
+
+## Reference
+
+- Example: `apps/example-empty/smoke.cases.json` (monorepo).
+- Package API: `loadStaticSmokeConfig`, `runStaticSmokeTest`, `runPreviewStaticSmokeTest`, `auditCacheLogs` from `@se-studio/site-check/smoke-test`.

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.