@se-studio/skills 1.5.4 → 1.5.6

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.5.6
+
+### Patch Changes
+
+- Media wrapper entries now default their `name` (Contentful list label) to the linked asset's title when created via `create media` or `visualAssetFilename` shorthands. Document the convention in editor playbooks and skills; avoid migration-style `Wrapper for {assetId}` labels.
+
+## 1.5.5
+
+### Patch Changes
+
+- d1a119c: Add `contentful-cms-create-editor-playbooks` skill and reference docs for customer editor playbook rollouts (Pedestal, OM1, PointMe, SE website).
+
 ## 1.5.4
 
 ### Patch Changes

package/package.json

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

package/references/contentful-cms-editor-playbooks/PATTERNS.md

@@ -0,0 +1,160 @@
+# Editor playbook patterns (Brightline reference)
+
+Patterns from the Brightline + BrightLife Kids rollout (`brightline-sites` `docs/cms-editor/`). Use as templates when authoring playbooks for other customers.
+
+## Two-file pattern
+
+Every **specialized page category** gets two files:
+
+| File | Role |
+|------|------|
+| `docs/cms-editor/<projectKey>/<topic>.md` | Full playbook — URL patterns, content stack, reference pages, component mapping |
+| `docs/cms-editor/<projectKey>/tasks/<topic>.md` | Short **capability task** — intent phrases + step checklist for `tasks-index` |
+
+Example (Brightline condition pages):
+
+- `brightline/condition-program-pages.md` → `cms-edit://customer/condition-program-pages`
+- `brightline/tasks/condition-program-pages.md` → `cms-edit://customer/task-condition-program-pages`
+
+Task stubs are **not** copies of the full playbook — they route agents to read the full resource first.
+
+## Task stub format
+
+```markdown
+# Capability: Condition & therapy program pages
+
+## Intent phrases
+
+- edit a condition page
+- new therapy program page
+
+## Requires capabilities
+
+`pages`
+
+## Prerequisites
+
+- Read `cms-edit://customer/condition-program-pages` (full playbook)
+- Read `cms-edit://customer/pages` for general page rules
+- `cms_edit ["index", "sync"]` when cloning from templates
+
+## Steps
+
+1. Identify URL under `/what-we-treat/` or `/care/therapy-programs/`
+2. Clone reference page (`task-clone-page`)
+3. Update Hero, FAQ collection, CTAs
+4. `preview urls` on staging
+5. `diff` → `save` → `task-publish-handoff`
+```
+
+**Parser rules** (`packages/contentful-cms/src/editor-pack/capabilities.ts`):
+
+- Title from `# Capability: <text>`
+- Intent phrases from bullet list under `## Intent phrases`
+- Resource name = `task-` + filename slug (without `.md`)
+
+## `pages.md` hub pattern
+
+General `pages.md` is the **router** — not a duplicate of every specialized playbook.
+
+Include:
+
+1. **Table** linking page types → `cms-edit://customer/<topic>` resources
+2. **When to use** — path prefixes, clone vs net-new
+3. **Templates** — `cms-edit list --type template` table
+4. **Reference pages** — 4–8 canonical clone sources with notes
+5. **Doc section → component mapping** — brief headings to registered types
+6. **Creating pages** — `task-create-page`, `task-create-from-document`, dry-run
+7. **Preview / publish handoff**
+
+Brightline excerpt:
+
+```markdown
+| Page type | Playbook |
+|-----------|----------|
+| Condition or therapy program | `cms-edit://customer/condition-program-pages` |
+| Insurance / pricing / cost | `cms-edit://customer/insurance-pricing-pages` |
+| Blog article | `cms-edit://customer/articles` |
+```
+
+## Specialized playbook sections
+
+| Section | Purpose |
+|---------|---------|
+| URL patterns | Prefix table with 2+ real examples |
+| Typical content stack | Ordered component/collection list |
+| Reference pages | "Clone when" column |
+| Hero / template guidance | Site-specific design rules |
+| FAQ / SEO / schema notes | When clinically or legally sensitive |
+| Workflow | Numbered steps |
+| Out of scope | Prevents wrong template or duplicate blocks |
+
+Fetch live markdown when `website.markdownAccess` is enabled: `https://<prod><path>.md`
+
+## Tier system (Brightline)
+
+### P0 — ship first
+
+| Brightline | BLK |
+|------------|-----|
+| `pages.md` | `pages.md` |
+| `ARTICLES.md` | `articles.md` |
+| `condition-program-pages` | `parent-coaching-topic-pages` |
+| `insurance-pricing-pages` | — |
+| `landing-pages-paid-media` | — |
+
+### P1
+
+| Brightline | BLK |
+|------------|-----|
+| `provider-pages` | `bilingual-locale-pages` |
+| `location-pages` | `resources-hub-pages` |
+| `partner-pages` | — |
+
+### P2
+
+| Brightline | BLK |
+|------------|-----|
+| `legal-policy-pages` | `legal-policy-pages` |
+| `learning-hub-hub-pages` | — |
+
+### Skipped (both sites)
+
+- `people.md` — `enablePerson=false`; clinicians covered by `provider-pages.md` on Brightline
+
+## Other playbook types
+
+| File | When |
+|------|------|
+| `articles.md` / `ARTICLES.md` | Article types, tag rules, featuredImage vs visuals |
+| `people.md` | `enablePerson=true` — team profiles, author import |
+| `blog-tag-matrix.md` | Complex tag governance (Brightline) |
+| `site-facts.json` | Canonical support email, phone — becomes `site-facts` resource |
+| `tasks/*.md` only | Overrides for core tasks (e.g. `import-blog-tag-matrix`) |
+
+## Generator behaviour
+
+From `packages/contentful-cms/src/editor-pack/generate.ts`:
+
+- `articles.md` and `ARTICLES.md` → `articles` resource (not duplicated as separate basename)
+- `pages.md` → sets `hasPagesPlaybook` in capabilities
+- Other `*.md` in project root → resource name = kebab-case basename
+- `tasks/*.md` → `task-<slug>` merged into `tasks-index.md`
+
+## Naming conventions
+
+- **Filenames:** kebab-case, match URL family (`legal-policy-pages`, `resources-hub-pages`)
+- **Resource URIs:** `cms-edit://customer/<basename>` — no `.md` suffix
+- **projectKey:** must match `project.json` `projectKey` exactly (`brightline`, not `brightline-website`)
+
+## Commit message pattern
+
+```
+docs(cms-editor): add Brightline P0 editor playbooks
+
+- pages.md hub + condition/insurance/landing playbooks
+- task stubs for tasks-index
+- regenerate editor-pack
+```
+
+Split P1/P2 into separate commits for easier review.

package/references/contentful-cms-editor-playbooks/PROJECT-ROLLOUT.md

@@ -0,0 +1,225 @@
+# Editor playbook rollout — project queue
+
+Suggested order after Brightline + BLK completion. Each project: audit → P0 → regen → doctor → push `develop` → P1 → P2.
+
+Skill: **`contentful-cms-create-editor-playbooks`**
+
+## Rollout order
+
+| # | Project | Repo path | Branch | Hosted MCP |
+|---|---------|-----------|--------|------------|
+| 1 | Pedestal Health | `~/source/customers/pedestal/pedestal-sites` | `develop` | `pedestal.content.se.studio` (verify in repo) |
+| 1b | Headwater Science | same monorepo | `develop` | separate space — second pass |
+| 2 | OM1 | `~/source/customers/om1/om1-website` | `develop` | `om1.content.se.studio` |
+| 3 | PointMe | `~/source/customers/pointme/develop-marketing-site` | `develop` | `pointme.content.se.studio` |
+| 4 | SE Studio | `~/source/se/se-website-2026` | `develop` | `se-website-2026.content.se.studio` |
+
+---
+
+## 1. Pedestal (`pedestal-sites`)
+
+**Config:** `cms-edit/pedestal-health/project.json` → `projectKey: pedestal-health`, `appDir: apps/pedestal-website`
+
+**Current state:** `docs/cms-editor/pedestal-health/ARTICLES.md` only — no `pages.md`, no specialized playbooks.
+
+**Routing signals** (`apps/pedestal-website/src/lib/constants.ts`):
+
+| Flag | Value |
+|------|-------|
+| `enablePerson` | `true` → need `people.md` |
+| `ARTICLES_BASE` | `''` (root-relative article URLs) |
+| `markdownArticleTypeSlugs` | `resources/publications`, `resources/news` |
+| `enablePrimaryTagPartOfSlug` | `true` |
+| Homepage | `index` (standard — omit `website.homepageSlug` in `project.json`) |
+
+### Suggested tiers
+
+**P0**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `pages.md` | Doctor requires when pages enabled |
+| `articles.md` | Rename/normalize from `ARTICLES.md` (either filename works; pick one) |
+| `people.md` | Persons enabled + `/people/` routes |
+| `publications-pages.md` | Core product — publications with poster/download rules |
+| `news-pages.md` | Press/news article type patterns |
+
+**P1**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `therapeutic-area-pages.md` | Disease/TA landing pages if distinct URL prefix |
+| `solutions-pages.md` | Product/solution family pages |
+| `resources-hub-pages.md` | `/resources/` index behaviour |
+
+**P2**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `legal-policy-pages.md` | Privacy, terms, compliance |
+
+**Headwater (`headwater-science`):** Repeat audit separately — same monorepo patterns but different content model and `projectKey`. Only `ARTICLES.md` exists today.
+
+---
+
+## 2. OM1 (`om1-website`)
+
+**Config:** `cms-edit/project.json` → `projectKey: om1`, single-site layout
+
+**Current state:** No `docs/cms-editor/` files — start from scratch.
+
+**Routing signals:**
+
+| Flag | Value |
+|------|-------|
+| `enablePerson` | `true` → `people.md` |
+| `ARTICLES_BASE` | `/resources` |
+| `PEOPLE_BASE` | `/team` |
+| `enableArticleTypeIndex` | `true` |
+| `enablePrimaryTagPartOfSlug` | `true` |
+| `TOPICLESS_ARTICLE_TYPE_SLUGS` | `ebooks` — document in articles playbook |
+
+### Suggested tiers
+
+**P0**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `pages.md` | General marketing pages |
+| `articles.md` | Resources hub — blog, ebooks, publications |
+| `people.md` | Team profiles at `/team/` |
+| `resource-article-pages.md` | Standard `/resources/{type}/{topic}/{slug}/` articles |
+
+**P1**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `ebook-pages.md` | Topicless URL shape for ebooks |
+| `solutions-pages.md` | Product/solution pages if distinct prefix |
+| `events-webinars-pages.md` | If event content type exists |
+
+**P2**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `legal-policy-pages.md` | Compliance |
+
+**Audit tip:** Inventory `/resources/` paths from sitemap; peek top-traffic solution and resource pages before writing component stacks.
+
+---
+
+## 3. PointMe (`develop-marketing-site`)
+
+**Config:** `cms-edit/project.json` → `projectKey: pointme`
+
+**Current state:** No `docs/cms-editor/` — start from scratch.
+
+**Routing signals:**
+
+| Flag | Value |
+|------|-------|
+| `enablePerson` | `true` |
+| `ARTICLES_SLUG` | `insights` |
+| `PEOPLE_BASE` | `/insights/author` (authors under insights, not `/people/`) |
+| `enableArticleTypeIndex` | `true` |
+| `enableTagsIndex` | `false` — tag pages under `/insights/{tag}/` |
+| `enablePrimaryTagPartOfSlug` | `false` |
+
+**Note:** Marketing site only — product app (`/home`, `/search`) is AWS; playbooks cover Vercel marketing routes only.
+
+### Suggested tiers
+
+**P0**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `pages.md` | About, concierge, marketing LPs |
+| `articles.md` | Insights blog — primary content type |
+| `insights-author-pages.md` | Author profiles at `/insights/author/{slug}/` (not generic `people.md` — custom PEOPLE_BASE) |
+| `insights-hub-pages.md` | `/insights/` index and tag landing pages |
+
+**P1**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `concierge-pages.md` | If `/concierge/` is a distinct template family |
+| `landing-pages-paid-media.md` | Campaign LPs if `indexed: false` pattern exists |
+
+**P2**
+
+| Playbook | Rationale |
+|----------|-----------|
+| `legal-policy-pages.md` | Privacy, terms |
+
+**Audit tip:** Map CloudFront-routed marketing paths only; exclude AWS product URLs from page inventory.
+
+---
+
+## 4. SE Studio (`se-website-2026`) — hard mode
+
+**Config:** `cms-edit/project.json` → `projectKey: se2026`
+
+**Current state:** `docs/cms-editor/se2026/pages.md` and `articles.md` exist — **extend, don't replace blindly**.
+
+**Why hard:** Site is **not designed for arbitrary custom marketing pages**. Page model is a small set of reference layouts (home, about, services, demo landing) using **General Page** template with `topContent` + `content`. New pages should **clone references**, not invent new component families.
+
+**Routing signals:**
+
+| Flag | Value |
+|------|-------|
+| `enablePerson` | `false` — **no `people.md`** |
+| Team content | **Person** entries in **Team grid** collection |
+| `enableTag` | `false` — simpler article model |
+| `ARTICLES_BASE` | `''` — work/video/blog article types |
+| `enableArticleTypeIndex` | `false` |
+
+### Suggested work (not traditional P0/P1/P2)
+
+| Action | Rationale |
+|--------|-----------|
+| **Tighten** existing `pages.md` | Ensure reference table, component mapping, and out-of-scope are current |
+| **Tighten** `articles.md` | Work / video / blog rules, case study picks in **Article browser** collections |
+| **Avoid** many specialized page playbooks | No `/providers/`-style families |
+| Optional `work-case-study-pages.md` | If editors frequently add case studies |
+| Optional `demo-landing-pages.md` | Campaign clones from `/demo-landing` |
+| **Do not** add `people.md` | Use articles + Team grid Person guidance inside `pages.md` |
+
+### SE website editor guardrails (put in `pages.md`)
+
+- New marketing pages: clone `/about`, `/services`, or `/demo-landing` — not blank canvas
+- Homepage slug `index` (URL `/`)
+- Agent test pages: `indexed: false`
+- Component gaps → **Generic** fallback + engineering flag
+- Read `cms-edit://customer/brand` for voice
+
+**Audit tip:** `cms-edit peek --page-slug /about` and `/services` — document exact collection nesting before any new playbook.
+
+---
+
+## Per-project audit checklist
+
+Copy into working notes for each site:
+
+```
+[ ] project.json validated
+[ ] constants.ts flags recorded
+[ ] sitemap categories table
+[ ] templates listed (cms-edit list --type template)
+[ ] 3+ reference pages peek'd
+[ ] capabilities.json reviewed
+[ ] P0 playbook list approved by user
+[ ] pages.md hub links all specialized playbooks
+[ ] task stub per specialized playbook
+[ ] editor-pack regenerated
+[ ] project doctor clean
+[ ] pushed to develop
+```
+
+## Completed reference
+
+**Brightline + BLK** (`brightline-sites`) — full P0–P2 shipped. Use as gold standard:
+
+- `docs/cms-editor/brightline/` — 8 specialized + hub + articles + blog-tag-matrix
+- `docs/cms-editor/brightlifekids/` — 6 specialized + hub + articles
+
+See `PATTERNS.md` for tier tables.

package/references/deps-update/projects.registry.json

@@ -8,6 +8,10 @@
     "major": 11,
     "engines": "11.x"
   },
+  "minimumReleaseAge": {
+    "minutes": 1440,
+    "exclude": ["@se-studio/*"]
+  },
   "projects": [
     {
       "key": "se-core-product",

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

@@ -30,6 +30,8 @@ Use this skill when you need to read or edit content in Contentful CMS using the
 All `save` operations create **draft** versions. A human must review and publish in Contentful.
 
 **Assets:** Upload **is** supported (`asset upload`). Default workflow: **search and reuse** existing assets first (`index sync` → `asset search`). When uploading:
+- **Hosted MCP:** always `cms_edit_request_staged_upload` → curl → `asset upload --staged` (never `--base64`)
+- **Local CLI:** `--base64` or `--url` when user approves local CLI
 - Use a **sensible fileName** and **descriptive title** (and alt text where the site uses it)
 - Avoid oversized images — width over **2000px** is usually wasteful for web (exact limits vary by project; check `asset audit` / media review guidance)
 - Prefer `--if-exists-by-filename` to avoid duplicates
@@ -120,7 +122,7 @@ cms-edit set @c0 anchor "hero-section"
 cms-edit set @c1:cmsLabel="Hero — School avoidance" @c2:cmsLabel="What is school avoidance?" @c3:cmsLabel="Signs of school avoidance"
 cms-edit set @c1:heading="Title A" @c2:heading="Title B"
 ```
-Each token is `@ref:fieldName=value`. All values are scalar (string, boolean, number). Flags like `--link`, `--links`, `--file` do not apply in multi mode.
+Each token is `@ref:fieldName=value`. All values are scalar (string, boolean, number). Flags like `--link`, `--links`, `--json` do not apply in multi mode.
 
 **Entry link fields** (template, articleType, etc. — value is the linked entry ID):
 ```bash
@@ -158,7 +160,7 @@ For any content with multiple paragraphs or newlines, use `printf` piped to stdi
 printf '## Why it matters\n\nOur platform helps teams **move faster**.\n\n- Instant setup\n- No code required\n' | cms-edit rtf @c1 body --markdown -
 
 # Also correct — file input
-cms-edit rtf @c1 body --markdown --file path/to/file.md
+cms-edit rtf @c1 body --markdown --content "# Heading\n\nBody."
 cms-edit rtf @c1 body --markdown - < path/to/file.md
 ```
 
@@ -170,7 +172,7 @@ cms-edit rtf @c1 body --markdown "Simple single-paragraph body text with **bold*
 
 **Surgical rich text replace** (compliance / quidget tokens — does not re-import the whole field):
 
-- Matching is **per Contentful text node** only. If the author split a phrase with bold (e.g. `**Annual fee: **$95`), the string `Annual fee: $95` will **not** match as one piece; use a shorter `--find` or full `rtf … --file`.
+- Matching is **per Contentful text node** only. If the author split a phrase with bold (e.g. `**Annual fee: **$95`), the string `Annual fee: $95` will **not** match as one piece; use a shorter `--find` or full `rtf … --content`.
 - Quidget strings contain `*`, which Markdown would treat as italic — use **`--replace-plain`**, not `--replace`.
 
 ```bash
@@ -246,7 +248,7 @@ Same as Component plus:
 When adding body content and a CTA (e.g. PDF download) to an article:
 
 1. `cms-edit open --article-slug <slug>` (or `open --id <id>`)
-2. Set body: `cms-edit rtf @<ref> body --markdown "..."` or `--markdown --file path/to.md`. If you need to add a body component first, use `add` then `rtf`.
+2. Set body: `cms-edit rtf @<ref> body --markdown "..."` or `--content` / `--base64`. If you need to add a body component first, use `add` then `rtf`.
 3. `cms-edit add CTA --target bottomContent`
 4. Set CTA links: use `--type external --label "Download PDF" --href <url>` for an external PDF URL, or `--type download --label "Download PDF" --asset-id <asset-id>` for a Contentful asset (get the ID from `cms-edit asset search "..."` or `asset info <id>`).
 5. `cms-edit save`
@@ -369,13 +371,23 @@ cms-edit asset search "hero background"
 cms-edit asset search --filename istockphoto-123.jpg
 cms-edit asset search --filename-match 'istockphoto-.*'
 
-# Upload from local file, URL, or base64
-cms-edit asset upload ./poster.jpg --title "Poster"
+# Local CLI — URL or base64 (hosted MCP rejects --base64)
 cms-edit asset upload --url https://example.com/image.jpg --if-exists-by-filename
 cms-edit asset upload --base64 "$B64" --mime image/png --file-name poster.png
 
-# Upload and create a Media wrapper in one step
-cms-edit asset upload ./figure.png --with-media --media-name "Figure 1" --media-position Middle
+# Hosted MCP — always staged upload for binary files
+# cms_edit_request_staged_upload → curl uploadUrl → consumeArgs
+# cms_edit ["asset", "upload", "--staged", "<uploadId>", "--mime", "image/png", "--file-name", "photo.png"]
+
+# Upload and create a Media wrapper in one step (--media-name defaults to asset title)
+cms-edit asset upload ./figure.png --with-media --media-position Middle
+
+# Create a Media wrapper for an existing asset (name defaults to asset title)
+cms-edit create media --asset-id <asset-id>
+
+# Fix a badly labelled Media wrapper (migration "Wrapper for …" labels)
+cms-edit batch set <media-entry-id>:name=<asset-title>
+cms-edit batch save
 
 # Get asset details
 cms-edit asset info 5xKj2abcDef
@@ -430,10 +442,10 @@ cms-edit create tag --slug easl-congress-2026 --name "EASL Congress 2026" --tag-
   --description "Research presented at EASL Congress 2026." --featured-image <logoAssetId>
 
 # Full fields via JSON
-cms-edit create tag --json-file tag.json --tag-type presentation-type --if-not-exists
+cms-edit create tag --json '{"slug":"presentation"}' --tag-type presentation-type --if-not-exists
 
 # Batch bootstrap
-cms-edit create taxonomy-from-json --file taxonomy.json --if-not-exists
+cms-edit create taxonomy-from-json --json '{"tagTypes":[...]}' --if-not-exists
 
 # Idempotent single-entry creates
 cms-edit create tag-type --slug conference-venue --name "Conference Venue" --if-not-exists
@@ -664,9 +676,9 @@ cms-edit peek --id <entryId>         # Look up by entry ID
 Run a sequence of operations from a JSON file or stdin.
 
 ```bash
-cms-edit batch run --file ops.json            # Run batch ops from file
+cms-edit batch run --json '[...]'            # Run batch ops from inline JSON
 echo '[...]' | cms-edit batch run             # Pipe from stdin
-cms-edit batch run --file ops.json --dry-run  # Validate without saving
+cms-edit batch run --json '[...]' --dry-run  # Validate without saving
 ```
 
 Supported ops: `open`, `set`, `rtf`, `rtf-replace`, `save`, `add`, `links-add`.
@@ -700,8 +712,8 @@ Example `ops.json` — update an existing page with a new CTA that has two butto
 Create a complete page or article — including all components, fields, and CTA links — from a single declarative JSON file. This is the recommended approach for creating multiple pages or articles in bulk.
 
 ```bash
-cms-edit create from-json --file page.json            # Create from file
-cms-edit create from-json --file page.json --dry-run  # Preview without writing
+cms-edit create from-json --json '{...}'            # Create from inline JSON
+cms-edit create from-json --json '{...}' --dry-run  # Preview without writing
 cat page.json | cms-edit create from-json             # Pipe from stdin
 ```
 

package/skills/contentful-cms-create-editor-playbooks/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: contentful-cms-create-editor-playbooks
+description: "Create and ship cms-editor playbooks for customer sites (audit page inventory, tier P0/P1/P2 playbooks, task stubs, regenerate editor-pack). Use for Pedestal, OM1, PointMe, SE website, or repeating the Brightline playbook rollout."
+---
+
+# Create cms-editor playbooks
+
+Use this skill when a customer site needs **hosted MCP editor playbooks** — the `docs/cms-editor/<projectKey>/` handbooks that become `cms-edit://customer/*` resources after editor-pack generation.
+
+**Reference files** (read when drafting playbooks):
+
+| File | Purpose |
+|------|---------|
+| `.agents/references/contentful-cms-editor-playbooks/PATTERNS.md` | Two-file pattern, sections, naming, Brightline examples |
+| `.agents/references/contentful-cms-editor-playbooks/PROJECT-ROLLOUT.md` | Rollout queue (Pedestal → OM1 → PointMe → SE website) and per-site audit hints |
+
+## When to use
+
+| Situation | Action |
+|-----------|--------|
+| New site with only `ARTICLES.md` or no playbooks | Full rollout (audit → P0 → regen → doctor) |
+| Site has page categories editors ask about repeatedly | Add specialized playbook + task stub |
+| After Brightline-style rollout on another customer | Follow this skill end-to-end |
+| User says "playbooks for Pedestal / OM1 / PointMe / SE website" | Read `PROJECT-ROLLOUT.md` first |
+
+**Precursor (optional but recommended):** If `docs/cms-guidelines/**` is stale or missing screenshots, run **`contentful-cms-update-cms-guidelines`** (`sync` or `fresh`) **before** playbooks so `components-index` and guideline snippets are accurate.
+
+## Pit-of-success order
+
+1. **Locate** customer repo + `cms-edit/<site>/project.json` → note `projectKey`, `appDir`
+2. **Audit** routing, page inventory, capabilities (Phase 1)
+3. **Plan** playbook set by tier (Phase 2) — propose to user before writing P1/P2
+4. **Write** playbooks + task stubs (Phase 3)
+5. **Regenerate** editor pack + doctor (Phase 4) — skill **`contentful-cms-regenerate-editor-pack`**
+6. **Commit + push** customer `develop` (never manual Vercel deploy)
+
+Editors consume playbooks via skill **`contentful-cms-editor-tasks`** (`tasks-index` → `task-*` → specialized playbook).
+
+## Phase 1 — Site audit
+
+Run from the **customer repo root**. Record findings in your working notes before writing files.
+
+### Config and routing
+
+```bash
+# projectKey must match docs/cms-editor/<projectKey>/
+cat cms-edit/<site>/project.json   # or cms-edit/project.json (single-site)
+
+# Routing flags and URL bases
+cat <appDir>/src/lib/constants.ts
+```
+
+Check:
+
+| Signal | Source | Playbook impact |
+|--------|--------|-----------------|
+| `projectKey` | `project.json` | Directory name under `docs/cms-editor/` |
+| `enablePerson` | `constants.ts` | `people.md` when true (doctor warns if missing) |
+| `enableArticleTypeIndex` / article routes | `constants.ts` | `articles.md` depth |
+| `ARTICLES_BASE`, `TAGS_BASE`, `PEOPLE_BASE` | `constants.ts` | URL patterns in playbooks |
+| `homepageSlug` | `project.json` `website` (default `index`) | Routing examples |
+| `markdownArticleTypeSlugs` | `constants.ts` | Article URL shapes (Pedestal) |
+
+### Page inventory
+
+Build a **category table** (URL prefix → human label → clone reference slug):
+
+1. Production sitemap: `curl -s https://<prod>/sitemap.xml` or app's `pnpm sitemap-validate` config
+2. Group paths by prefix (`/resources/`, `/insights/`, `/what-we-treat/`, etc.)
+3. Pick 1–3 **canonical clone sources** per category (`peek --page-slug`, live `.md` URLs)
+
+### CMS capabilities
+
+With dev server + tokens in `.env.local`:
+
+```bash
+cms-edit project validate --project-config cms-edit/<site>/project.json
+cms-edit editor-pack generate --project-config cms-edit/<site>/project.json   # dry run if pack exists
+cms-edit list --type template
+cms-edit peek --page-slug /about    # adjust per site
+```
+
+Read generated `capabilities.json` (or editor-pack copy) for `content.pages`, `content.articles`, `content.persons`.
+
+### Skip rules
+
+| Condition | Skip |
+|-----------|------|
+| `enablePerson === false` | `people.md` (SE website — team via **Person** entries in collections, not `/people/` routes) |
+| No distinct URL category with ≥3 pages | Specialized playbook — fold into `pages.md` |
+| Page type is engineering-only | Document in `pages.md` "out of scope" instead |
+
+## Phase 2 — Plan playbook tiers
+
+Propose a tier list to the user. Ship **P0 first**, regen + doctor, then P1/P2 in follow-up commits.
+
+### P0 (always aim to ship first)
+
+| File | When |
+|------|------|
+| `pages.md` | Site has `content.pages` — **required** (doctor + checklist) |
+| `articles.md` or `ARTICLES.md` | Site has articles — either filename works |
+| `people.md` | `enablePerson === true` |
+| 1–3 **specialized** playbooks | Highest editor traffic (see `PROJECT-ROLLOUT.md` per site) |
+
+### P1 — Secondary page families
+
+Specialized playbooks for distinct URL families (provider, location, resources hub, bilingual locale, etc.).
+
+### P2 — Low-frequency / compliance
+
+Legal/policy, niche hub indexes, partner microsites.
+
+### `pages.md` as hub
+
+The general `pages.md` must link to every specialized playbook:
+
+```markdown
+| Page type | Playbook |
+|-----------|----------|
+| Condition or therapy program | `cms-edit://customer/condition-program-pages` |
+```
+
+See `PATTERNS.md` for the full Brightline hub example.
+
+## Phase 3 — Write playbooks
+
+**Authoring path:** `docs/cms-editor/<projectKey>/`
+
+### File types
+
+| Path | Becomes | Notes |
+|------|---------|-------|
+| `pages.md` | `cms-edit://customer/pages` | Sets `hasPagesPlaybook`; checklist auto-links |
+| `articles.md` or `ARTICLES.md` | `cms-edit://customer/articles` | Special-cased in generator |
+| `people.md` | `cms-edit://customer/people` | When persons enabled |
+| `<topic>.md` | `cms-edit://customer/<topic>` | kebab-case basename = resource name |
+| `tasks/<slug>.md` | `cms-edit://customer/task-<slug>` | Appears in `tasks-index` |
+
+**Do not** put task stubs in the root — only under `tasks/`.
+
+### Specialized playbook sections
+
+Each `<topic>.md` should include:
+
+1. **Title** — `# <Human name> — <Site>`
+2. **URL patterns** — table with examples
+3. **Typical content stack** — component/collection order
+4. **Reference pages** — clone sources with public paths
+5. **Template** — which Contentful template label
+6. **Workflow** — numbered steps ending in preview → diff → save → publish handoff
+7. **Out of scope** — what editors must not do
+
+Start from template: `packages/contentful-cms/docs/cms-edit-project-template/docs/cms-editor/example/pages.md`
+
+### Task stub (required for tasks-index)
+
+For each specialized playbook, add `tasks/<topic>.md`:
+
+```markdown
+# Capability: <Short title>
+
+## Intent phrases
+
+- <phrase editors might say>
+- ...
+
+## Requires capabilities
+
+`pages`   # or `articles`, `persons`
+
+## Prerequisites
+
+- Read `cms-edit://customer/<topic>`
+- Read `cms-edit://customer/pages`
+
+## Steps
+
+1. ...
+```
+
+Parser reads `# Capability:` title and `## Intent phrases` bullets for `tasks-index.md`. See `PATTERNS.md`.
+
+### SE website constraint
+
+`se-website-2026` is **not** a free-form marketing site. Playbooks must:
+
+- Emphasize **clone from reference pages** (`/index`, `/about`, `/services`, `/demo-landing`)
+- Document **General Page** template + `topContent` / `content` regions (existing `pages.md`)
+- Treat new page types as **exceptions** — flag component gaps, use **Generic** fallback
+- **No** `people.md` — `enablePerson=false`; team content is **Person** entries inside **Team grid**
+- Article playbooks cover work/video/blog — not arbitrary landing pages
+
+Read existing `docs/cms-editor/se2026/pages.md` before extending; prefer tightening scope over adding many specialized playbooks.
+
+## Phase 4 — Regenerate and validate
+
+Follow **`contentful-cms-regenerate-editor-pack`**:
+
+```bash
+cms-edit project validate --project-config cms-edit/<site>/project.json
+cms-edit editor-pack generate --project-config cms-edit/<site>/project.json
+cms-edit project doctor --project-config cms-edit/<site>/project.json
+```
+
+Doctor checks:
+
+- `pages.md` present when pages capability on
+- `articles.md` when articles capability on
+- `people.md` when persons capability on
+- Editor-pack resources match hand-authored files
+
+Review diff:
+
+- `tasks-index.md` lists new `task-*` entries with intent phrases
+- `checklist.md` links `pages` / `articles` playbooks
+- `manifest.json` includes new resource names
+- `overview.md` references new playbooks
+
+## Phase 5 — Commit and publish
+
+In the **customer repo** (not se-core-product):
+
+```bash
+git add docs/cms-editor/<projectKey>/ cms-edit/<site>/editor-pack/
+git commit -m "docs(cms-editor): add <site> editor playbooks (P0)"
+git push origin develop
+```
+
+Hosted MCP rebuilds from git push — **do not** run `vercel deploy` or `cms-edit:deploy`.
+
+## Multi-site monorepos
+
+| Repo | Sites | `projectKey` folders |
+|------|-------|----------------------|
+| `pedestal-sites` | Pedestal Health, Headwater | `pedestal-health`, `headwater-science` |
+| `brightline-sites` | Brightline, BLK | `brightline`, `brightlifekids` |
+
+Each site has its own `cms-edit/<site>/project.json` and `docs/cms-editor/<projectKey>/`. Roll out **one site at a time**.
+
+## Suggested rollout queue
+
+See **`PROJECT-ROLLOUT.md`** for per-site P0/P1/P2 checklists. Default order:
+
+1. **Pedestal** (`pedestal-health`, then `headwater-science`)
+2. **OM1**
+3. **PointMe**
+4. **SE website** (`se2026`) — hardest; extend existing playbooks cautiously
+
+## Related skills
+
+| Skill | When |
+|-------|------|
+| `contentful-cms-regenerate-editor-pack` | After any playbook change |
+| `contentful-cms-editor-tasks` | How editors consume playbooks |
+| `contentful-cms-update-cms-guidelines` | Refresh guidelines/screenshots first |
+| `contentful-cms-core` | `peek`, `list`, `create from-json` during audit |
+| `se-marketing-sites-curate-showcase-mocks` | Showcase data before screenshot refresh |
+
+## Related docs
+
+| Doc | Purpose |
+|-----|---------|
+| `docs/RELATED_PROJECTS.md` | Repo paths, Contentful spaces |
+| `packages/contentful-cms/docs/cms-edit-project-template/README.md` | `project.json`, playbook stubs |
+| `packages/contentful-cms/docs/mcp/hosted-guide.md` | MCP resource URIs |

package/skills/contentful-cms-media-review/SKILL.md

@@ -28,9 +28,9 @@ The playbook defines phases, hosted vs local limits, and confirmation gates. Thi
 
 | Goal | Command |
 |------|---------|
-| Failures JSON | `cms-edit --json asset review` |
-| Full + usage (local) | `cms-edit --json asset review --include-passing --include-usage --usage-limit 0` |
-| Usage sample (hosted) | `cms-edit --json asset review --include-usage --usage-limit 50` |
+| Failures JSON | `cms-edit --json-output asset review` |
+| Full + usage (local) | `cms-edit --json-output asset review --include-passing --include-usage --usage-limit 0` |
+| Usage sample (hosted) | `cms-edit --json-output asset review --include-usage --usage-limit 50` |
 
 Hosted MCP: **no `--space`**. Do not use `--usage-limit 0` with `--include-passing` on hosted MCP.
 
@@ -75,6 +75,8 @@ Summarize: totals, top `issueCounts`, quick wins (alt, GIFs, stock filenames).
 
 **Fixes (user-approved only):** `cms-edit asset set-description <id> "…"` — drafts only, no publish.
 
+**Media entry labels:** The Contentful list label for a **Media** wrapper is its `name` field — **set it to the linked asset's `title`**, not `visual-{assetId}`, `Wrapper for {assetId}`, or the filename. When creating wrappers: `cms-edit create media --asset-id <id>` (name defaults to asset title) or `asset upload --with-media` (use `--media-name` only when you need a distinct label for multiple wrappers on the same asset). To fix existing entries: `cms-edit batch set <media-entry-id>:name=<asset-title>` then `batch save`.
+
 For per-page alt work: **`contentful-cms-alt-text-audit`**.
 
 ## Image guide (optional extension)
@@ -82,7 +84,7 @@ For per-page alt work: **`contentful-cms-alt-text-audit`**.
 When the client wants a **reference guide** (not just remediation):
 
 ```bash
-cms-edit --json asset review --include-passing --include-usage --usage-limit 0 > docs/image-inventory.json
+cms-edit --json-output asset review --include-passing --include-usage --usage-limit 0 > docs/image-inventory.json
 ```
 
 - Cache AI descriptions: `docs/descriptions/{assetId}.json` (write-through per image)

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

@@ -125,6 +125,7 @@ In Claude Desktop (hosted integration): ask to read `cms-edit://customer/routing
 
 | Prior work | Skill |
 |------------|-------|
+| New hand-authored playbooks | `contentful-cms-create-editor-playbooks` |
 | Guidelines changed | `contentful-cms-update-cms-guidelines` |
 | New registration | `se-marketing-sites-register-cms-features` |
 | Editor Integrations setup | `contentful-cms-setup` (hosted path) |

package/skills/contentful-cms-rich-text/SKILL.md

@@ -10,11 +10,11 @@ Use this skill when editing **rich text** fields (body, additionalCopy) and inse
 ## Rich text (rtf)
 
 - **Replace** body with Markdown (single paragraph, no newlines): `cms-edit rtf @c1 body --markdown "Simple body with **bold** and [link](https://example.com)."`
-- **Multiline content** — use `printf` piped to stdin; `\n` in a double-quoted shell string is **not** a newline in bash:
+- **Multiline content** — use `--content` or `--base64` (hosted MCP has no filesystem):
   ```bash
-  printf '## Heading\n\nParagraph with **bold** and [link](https://example.com).\n' | cms-edit rtf @c1 body --markdown -
+  cms-edit rtf @c1 body --markdown --content "## Heading\n\nParagraph with **bold**."
   ```
-- Use `--file path/to/file.md` or stdin (`-`) for long content.
+- For large payloads via MCP: `--base64 <encoded-markdown>`.
 - Markdown supported: headings, bold/italic, links, lists, blockquote, inline code, `---`.
 
 Use **set** for scalar and link fields; use **rtf** only for rich text fields.
@@ -56,11 +56,8 @@ cms-edit rtf replace @c1 body \
 Apply multiple find/replace operations in a single call. All ops are validated before any write.
 
 ```bash
-# From file
-cms-edit rtf patch @c0 body --file patch.json
-
-# From stdin
-echo '[{"find":"old","replaceWith":"new","mode":"exactlyOne"}]' | cms-edit rtf patch @c0 body
+cms-edit rtf patch @c0 body --json '[{"find":"old","replaceWith":"new","mode":"exactlyOne"}]'
+# Or --json-base64 for large patch arrays
 ```
 
 Each op in the JSON array supports:

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

@@ -25,8 +25,8 @@ If no brand context is available, ask the user for these details.
 | About | AboutPage + Organization |
 | Service/Product | Service or Product |
 | Pricing | Product with Offer |
-| Blog listing | CollectionPage |
-| Article | Article or BlogPosting |
+| Blog listing | CollectionPage + Blog + ItemList |
+| Article | BlogPosting |
 | FAQ | FAQPage with Question/Answer |
 | Contact | ContactPage |
 | Team/People | ProfilePage or Person |
@@ -35,33 +35,59 @@ If no brand context is available, ask the user for these details.
 
 ## Phase 2: Generate Mustache Templates
 
-Create JSON-LD templates using these standard Mustache variables:
+Create JSON-LD templates using runtime variables from `buildStructuredDataContext()` in `@se-studio/core-ui` (see `packages/core-ui/src/utils/structuredDataUtils.ts`).
 
-- `{{title}}` — page/article title
-- `{{seoDescription}}` — SEO meta description
-- `{{slug}}` — page slug
-- `{{publishDate}}` — article publish date
-- `{{updatedAt}}` — last modification date
-- `{{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
+Reference markup generators in `@se-studio/cms-seo` (`breadcrumbListMarkup`, `blogPostingMarkup`, `itemListMarkup`, etc.).
+
+### URLs and page
+
+- `{{baseUrl}}` — site origin with trailing slash (e.g. `https://www.example.com/`)
+- `{{{baseUrl}}}` — same, triple-brace for JSON-safe URLs in `@id` fields
+- `{{currentUrl}}` / `{{{currentUrl}}}` — full canonical URL of the current page
+- `{{page.title}}` — page or content title
+- `{{page.description}}` — SEO meta description
+- `{{page.slug}}` — content slug
+- `{{{page.imageUrl}}}` — OG image URL when featured image is set
+- `{{#page.breadcrumbs}}` — breadcrumb segments: `position`, `name`, optional `url`, `last`
+
+### Articles
+
+- `{{article.title}}`, `{{article.description}}`
+- `{{article.datePublished}}`, `{{article.dateModified}}` — ISO 8601 (not `article.date`)
+- `{{article.authorName}}`, `{{{article.authorUrl}}}` — primary author
+- `{{#article.authors}}` — multi-author: `name`, optional `url` per author
+- `{{{article.imageUrl}}}` — featured image URL
+
+### Person pages
+
+- `{{person.name}}`, `{{person.jobTitle}}`, `{{{person.imageUrl}}}`
+
+### Listing pages (ItemList)
+
+When the app wires `buildListingItems()` / `buildListingStructuredDataContext()` from `@se-studio/core-ui/server`:
+
+- `{{#listing.items}}` — `position`, `name`, `{{{url}}}`, `last` (for Mustache comma separation)
+
+Static brand data (organization address, social URLs, logo) belongs **in the CMS template**, not in code.
 
 ## Phase 3: Upload via cms-edit
 
 1. Check available fields:
    - `cms-edit schema page` — page content type fields
    - `cms-edit schema template` — template content type fields
-   - Look for `schemaOrg`, `jsonLd`, `structuredData`, or similar
-2. For **template-level** schemas (Organization, WebSite — shared): `cms-edit list --type template` → open → set
-3. For **page-level** schemas: open each page → set its schema field
-4. `cms-edit diff` then `cms-edit save`
+   - Look for `structuredData` or `indexPageStructuredData`
+2. For **template-level** schemas (Organization, WebSite, BreadcrumbList — shared): `cms-edit list --type template` → open → set
+3. For **article type** schemas (BlogPosting on `structuredData`, Blog/CollectionPage/ItemList on `indexPageStructuredData`): link on articleType entry
+4. For **page-level** subtype overrides (FAQPage, Product, Service): link on the page entry only
+5. `cms-edit diff` then `cms-edit save`
 
 ## Best Practices
 
 - Don't duplicate — template-level Organization schema covers all pages
-- Use specific types — `MedicalBusiness` over `LocalBusiness` if applicable
+- Link schema on **templates and types**, not on every article
+- Use specific types where they apply — `BlogPosting` for blog posts, `ProfilePage` for authors
+- BreadcrumbList `item` property: output only when `{{#url}}` is present on a segment
+- One FAQPage per URL — do not duplicate component-level and CMS-level FAQPage on the same page
 - Validate all required properties are present
 - Schema must reflect actual page content
 
@@ -72,4 +98,4 @@ Create JSON-LD templates using these standard Mustache variables:
 
 ## Related skills
 
-See the **core** skill for the full cms-edit workflow. See the **seo-descriptions** skill for meta description generation. For bulk audit/apply across all entries, schema linking, publish phases, and production verification, see **cms-seo-audit**.
+See the **core** skill for the full cms-edit workflow. See the **seo-descriptions** skill for meta description generation. For bulk audit/apply across all entries, schema linking, publish phases, and production verification, see **cms-seo-audit**.

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

@@ -1,11 +1,11 @@
 ---
 name: contentful-cms-setup
-description: "Guide a user through connecting hosted cms-edit MCP for Claude (Integrations + OAuth)."
+description: "Guide a user through connecting hosted cms-edit MCP for Claude or Grok (OAuth)."
 ---
 
 # Skill: cms-edit Setup
 
-Use this skill when the user wants to connect Claude to their Contentful site via **hosted cms-edit MCP**.
+Use this skill when the user wants to connect Claude or Grok to their Contentful site via **hosted cms-edit MCP**.
 
 Local stdio MCP and the setup wizard are **not supported**. Editors connect through the site's `/cms-edit` onboarding flow.
 
@@ -35,6 +35,39 @@ Use skill **`contentful-cms-editor-tasks`** for the tasks-index → capability p
 
 ---
 
+## Hosted setup (Grok Build)
+
+Use when the user wants cms-edit in **Grok Build** (not local stdio MCP).
+
+### Step 1: Configure Grok
+
+Add to `~/.grok/config.toml`:
+
+```toml
+[mcp_servers.cms-edit-<projectKey>]
+url = "https://<host>/api/mcp"
+enabled = true
+```
+
+The URL **must** end with `/api/mcp`. Use the MCP URL from the site's `/cms-edit` page.
+
+### Step 2: Connect
+
+1. In Grok, run `/mcps`
+2. Select the cms-edit server
+3. Press **`i`** to initiate OAuth (not just enable)
+4. Sign in with Contentful when prompted
+
+### Step 3: Verify
+
+Run `grok mcp doctor cms-edit-<projectKey>` or call `cms_edit_version` in a Grok session.
+
+**Reconnect:** `/mcps` → press `i` again if OAuth expires.
+
+Full guide: `packages/contentful-cms/docs/mcp/hosted-guide.md` (Grok Build section).
+
+---
+
 ## Developers (CLI + skills, not local MCP)
 
 For engineering work in a site repo (Cursor, Grok, terminal):
@@ -51,7 +84,10 @@ Do **not** register a local `mcpServers.cms-edit` entry in Claude Desktop — us
 ## Troubleshooting
 
 **OAuth / sign-in fails**
-→ Confirm the user was invited to the Contentful space and is signing in with the correct account.
+→ Confirm the user was invited to the Contentful space and is signing in with the correct account. In Grok, use `/mcps` → press `i` (not just toggle). Confirm config URL ends with `/api/mcp`.
+
+**Grok browser flashes and closes**
+→ Usually a redirect_uri mismatch before cms-edit v2.7.7+; upgrade the hosted deployment and retry OAuth.
 
 **`cms_edit` tool not available**
 → Reconnect via `/cms-edit` or Claude Integrations. Remove any legacy local MCP or `.mcpb` extension entries.

package/skills/se-marketing-sites-markdown-accuracy-review/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: se-marketing-sites-markdown-accuracy-review
+description: "LLM review of production markdown exports vs HTML pages. Use when auditing .md accuracy, running markdown-accuracy-audit artifacts, or writing docs/reports/markdown-accuracy-audit.md."
+---
+
+# Markdown accuracy review (LLM)
+
+Compare production **HTML** pages with their **`.md`** exports to judge whether markdown is an accurate representation of CMS content. Metrics collection is automated; **verdicts are written by the agent** using this rubric.
+
+## Prerequisites
+
+1. Run the collector from monorepo root:
+
+```bash
+node packages/site-check/markdown-accuracy-audit.mjs --site se2026 --path /about/ --dry-run
+node packages/site-check/markdown-accuracy-audit.mjs --delay-ms 500
+```
+
+2. Read artifacts under `docs/reports/.markdown-audit-artifacts/<site>/<slug>/`:
+   - `meta.json` — URLs, metrics, cache headers
+   - `page.html` — full HTML (`<script>` / `<style>` removed only)
+   - `page.md` — full markdown, verbatim
+
+**Do not truncate** HTML or markdown when reviewing. Read complete files.
+
+## Review rubric
+
+For each URL, assess:
+
+| Dimension | Question |
+|-----------|----------|
+| **Coverage** | Are substantive CMS blocks (headings, body, lists, link text, image alt text) present in markdown? |
+| **Fidelity** | Do title, H1, and key facts match HTML? Any wrong or invented content? |
+| **Expected omissions** | Nav, footer, cookie banners, forms, carousels, video players, and interactive widgets may be absent — note explicitly. |
+| **Markdown quality** | Sensible structure, working link hrefs, frontmatter completeness, canonical alignment. |
+| **Fetch health** | Check `meta.json` metrics — non-2xx or empty bodies are `Error`, not content verdicts. |
+
+## Verdicts
+
+Use exactly one:
+
+- **Accurate** — CMS content fully represented; omissions are only expected chrome/interactivity.
+- **Mostly accurate** — Core content matches; minor gaps (eyebrow text, secondary metadata, non-critical visuals).
+- **Partial** — Important sections missing or materially different, but primary message partly preserved.
+- **Inaccurate** — Wrong headings/facts, major missing blocks, or misleading representation.
+- **Error** — Fetch failed or empty response (see `meta.json` metrics).
+
+## Review column format
+
+2–4 sentences in the final report table:
+
+```text
+**Mostly accurate** — H1 and body copy match. Markdown omits the team photo grid and contact form (expected). Pre-heading eyebrow in HTML not exported.
+```
+
+## Report assembly
+
+Write [`docs/reports/markdown-accuracy-audit.md`](../../../../docs/reports/markdown-accuracy-audit.md):
+
+1. Run metadata (timestamp, site count, URL count).
+2. Summary table of verdict counts.
+3. Per-site sections with table columns: **URL | HTML size | MD size | HTML ms | MD ms | Cache | Review**.
+4. JSON sidecar [`docs/reports/markdown-accuracy-audit.json`](../../../../docs/reports/markdown-accuracy-audit.json) merging metrics + verdict + review text.
+
+Review in site batches (~6–13 URLs). Commit `.md` and `.json` to `dev`; artifacts dir stays gitignored.
+
+## Dry-run gate
+
+When asked for a dry run, collect **one** case (default: SE Studio `/about/`), perform the LLM review, and present a **single sample table row** for format approval before running all 51 smoke URLs.

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

@@ -87,12 +87,28 @@ jobs:
           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
+        if: always() && github.event_name == 'repository_dispatch'
+        uses: vercel/repository-dispatch/actions/status@44f4d342ebc265c58167a2aa77d5a0d5a6eb20fd
         with:
           name: "Vercel - <vercel-project-name>: deployment smoke"
+      # Vercel can miss the first GitHub status webhook; re-post after a short delay.
+      - name: Retry Deployment Check status for Vercel reconciliation
+        if: always() && github.event_name == 'repository_dispatch'
+        env:
+          CHECK_NAME: "Vercel - <vercel-project-name>: deployment smoke"
+          DEPLOYMENT_SHA: ${{ github.event.client_payload.git.sha }}
+          CHECK_STATE: ${{ job.status == 'success' && 'success' || 'failure' }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          sleep 30
+          gh api "repos/${GITHUB_REPOSITORY}/statuses/${DEPLOYMENT_SHA}" \
+            -f state="${CHECK_STATE}" \
+            -f context="${CHECK_NAME}" \
+            -f target_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
 ```
 
+Use the deployment commit SHA from `client_payload.git.sha`, not `github.sha`. Repeat the retry block in each job when a workflow has multiple Vercel projects (monorepos).
+
 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`).

package/skills/site-workflows-deps-update/SKILL.md

@@ -11,7 +11,7 @@ Update npm dependencies to **latest** in se-core-product and consumer repos that
 
 **Default:** Process **one repo per invocation**. At the end, summarize changes and offer the next project.
 
-**Never:** push to `main`/`master`; bump Next to 16; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`.
+**Never:** push to `main`/`master`; bump Next to 16; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`; bypass or remove `minimumReleaseAge`.
 
 ---
 
@@ -61,17 +61,27 @@ Commit the bootstrap copy as part of the deps update commit when you add it.
 
 ---
 
-## Step 3 — Pin overrides (before `--latest`)
+## Step 3 — Supply-chain policy + pin overrides
 
-`pnpm update -r --latest` would bump `next` → 16 and `@types/node` → 26. Add or verify this block in `pnpm-workspace.yaml` (values from registry `pinOverrides`):
+Every repo **must** have this block in `pnpm-workspace.yaml` (merge into existing file — do not remove other keys such as `allowBuilds`, repo-specific excludes, or PointMe's extra overrides):
 
 ```yaml
+minimumReleaseAge: 1440
+minimumReleaseAgeExclude:
+  - '@se-studio/*'
+
 overrides:
   next: ^15.5.19
   '@types/node': ^24.13.2
 ```
 
-Skip if `hasPinOverrides` is already true and values match. Idempotent — merge into existing `pnpm-workspace.yaml` without removing other keys (`minimumReleaseAge`, `allowBuilds`, etc.).
+- **`minimumReleaseAge: 1440`** — do not install packages published in the last 24 hours (supply-chain guard).
+- **`@se-studio/*` exclude** — our own packages may update immediately after npm publish.
+- **Keep repo-specific additional excludes** when present (e.g. vitest pins in se-core-product, `@emnapi/runtime` in se-website-2026, PointMe `mapbox-gl` / `react-day-picker` overrides).
+
+`pnpm update -r --latest` would bump `next` → 16 and `@types/node` → 26 without the overrides block. The overrides prevent that.
+
+**Never bypass `minimumReleaseAge`** during dependency updates. Do not remove the block, comment it out, or use undocumented pnpm flags. If a non-`@se-studio` package was published within 24 hours, it stays at the current version until it ages out — note that in the report and re-run later if needed.
 
 ---
 
@@ -80,14 +90,15 @@ Skip if `hasPinOverrides` is already true and values match. Idempotent — merge
 Bump the package manager to the **latest pnpm 11.x** in root `package.json`:
 
 ```bash
-LATEST_PNPM=$(npm view pnpm@11 version)
-# Set "packageManager": "pnpm@<LATEST_PNPM>" in package.json
-corepack use pnpm@${LATEST_PNPM}
+corepack use pnpm@11.9.0
+# Or: LATEST=$(npm view pnpm@11.9.0 version) && corepack use pnpm@${LATEST}
 pnpm -v   # confirm matches packageManager
 ```
 
 Keep `engines.pnpm` at `11.x` (do not jump to pnpm 12). If `engines.pnpm` is missing, add `"pnpm": "11.x"` alongside `"node": "24.x"`.
 
+Align nested `packageManager` fields (e.g. `apps/*/package.json`) with the root version when validate fails on a version mismatch.
+
 ---
 
 ## Step 5 — Update dependencies
@@ -96,12 +107,26 @@ Keep `engines.pnpm` at `11.x` (do not jump to pnpm 12). If `engines.pnpm` is mis
 pnpm update -r --latest
 ```
 
-If brightline or pedestal repos block fresh packages (`minimumReleaseAge: 1440`), retry with:
+Then explicitly align `@se-studio/*` where the repo uses them (omit packages the repo does not depend on):
 
 ```bash
-pnpm update -r --latest --no-minimum-release-age
+pnpm update -r \
+  @se-studio/ab-testing \
+  @se-studio/cms-seo \
+  @se-studio/contentful-cms@^3.0.1 \
+  @se-studio/contentful-rest-api \
+  @se-studio/core-data-types \
+  @se-studio/core-ui \
+  @se-studio/hubspot \
+  @se-studio/markdown-renderer \
+  @se-studio/project-build \
+  @se-studio/search \
+  @se-studio/site-check \
+  @se-studio/skills
 ```
 
+`@se-studio/*` resolves immediately via `minimumReleaseAgeExclude`. Other packages respect the 24-hour window.
+
 Safety re-pin after update:
 
 ```bash
@@ -155,6 +180,8 @@ Include in the summary:
 - Major dependency bumps (from the Step 1 audit diff)
 - pnpm version: before → after
 - Confirmed pins: Next 15.x, Node 24, `@types/node` ^24
+- Confirmed `minimumReleaseAge: 1440` and `@se-studio/*` exclude present
+- Packages still outdated because they are inside the 24-hour release window (if any)
 - Patches check bootstrapped (yes/no)
 - Remaining projects not yet updated
 
@@ -179,6 +206,7 @@ This is optional follow-up — the skill workflow always runs the check regardle
 | Issue | Action |
 |-------|--------|
 | `next` or `@types/node` still outdated to wrong major | Re-run overrides + safety re-pin; check `pnpm-workspace.yaml` overrides |
+| Non-`@se-studio` package still outdated after update | Likely within 24h of npm publish — wait and re-run; **do not** bypass `minimumReleaseAge` |
 | `corepack use` fails | Run `corepack enable` once, retry |
 | Validate fails after major bump | Check breaking-change release notes; fix or revert |
 | Repo path missing | Skip; note in report — see `docs/RELATED_PROJECTS.md` |