@se-studio/skills 1.5.10 → 1.6.0

package/CHANGELOG.md

@@ -1,11 +1,22 @@
 # @se-studio/skills
 
+## 1.6.0
+
+### Minor Changes
+
+- Add source readiness review as a core editor task, wire create-from-document / create-article / preview-verify to faithful package intake (no copy rewrite), and ship SOURCE-READINESS plus multi-site input examples for playbook authors.
+
+## 1.5.11
+
+### Patch Changes
+
+- Document smoke/deploy failure playbook and refuse-customer-patches guardrails (agent-session Step 3b).
+
 ## 1.5.10
 
 ### Patch Changes
 
 - Document lockfile sync enforcement (scripts, CI snippet, deps-update and smoke-test skill updates).
-- 2359f69: Add `site-workflows-stale-files-cleanup` skill and `references/stale-files-cleanup/` for repository hygiene audits on SE Studio marketing sites.
 
 ## 1.5.8
 

package/package.json

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

package/references/agent-session/customer-agents-block.md

@@ -22,6 +22,16 @@ Before non-trivial code, run the placement checklist (in the skill). Summary:
 
 If the checklist says **core**, stop and switch to core-first mode — do not patch `@se-studio` behaviour in this repo.
 
+### Deploy smoke failed?
+
+Do **not** change `baseUrl`, discovery routes, or add `getRequestBaseUrl()` to unblock Vercel Deployment Checks. That fix belongs in `@se-studio/site-check` (core-first).
+
+1. Follow the smoke/deploy failure playbook in `se-core-product` — `packages/skills/references/agent-session/smoke-deploy-failure-playbook.md`
+2. Bump `@se-studio/site-check@2.9.4+` after npm publish (`discovery.urlOrigin: auto`)
+3. Customer-only: curate new URLs in `smoke.cases.json` when CMS routes go live — not package assertion hacks
+
+Record `placement.decision` in `work/active/<feature>.yaml` before smoke/server-config commits aimed at deploy smoke.
+
 ### Core release order
 
 When work depends on a new `@se-studio/*` npm release:

package/references/agent-session/manifest.template.yaml

@@ -19,6 +19,8 @@ placement:
   rationale: One-site hero layout tied to OM1 Figma
   extract_to_core: null # pending | null
   extract_rationale: null
+  # Required before smoke/server-config commits for deploy-smoke goals (agent-session Step 3b):
+  # smoke_edit: null # curated-urls | blocked-on-core | defer-extract
 
 blocked_on: null # e.g. "@se-studio/core-ui@2.1.0"
 cms_session: null # set to feature slug when doing parallel CMS edits

package/references/agent-session/projects.registry.json

@@ -73,7 +73,8 @@
       "path": "~/source/customers/hopskipdrive/hsd-extended-port",
       "branch": "extended-port",
       "type": "customer",
-      "wip": true,
+      "contentfulSpaceIds": ["gqa3p93n5wse"],
+      "hostedMcp": ["cms-edit-hsd"],
       "validate": "pnpm validate"
     }
   ]

package/references/agent-session/refuse-customer-patches.md

@@ -0,0 +1,58 @@
+# Refuse customer patches (site-first guardrails)
+
+Agents in **site-first** mode must **refuse** customer-repo changes that belong in **`se-core-product`** (`@se-studio/*`), unless the user explicitly approves **`defer-extract`** in the manifest with `extract_to_core: pending` and a dated extraction plan.
+
+Run this table **in addition to** the placement checklist (`site-workflows-agent-session` Step 3) when the task touches smoke, deploy checks, shared packages, or infra.
+
+## Refusal triggers
+
+| Symptom, file, or request | Correct owner | Agent action (site-first) |
+|---------------------------|---------------|---------------------------|
+| Deploy / `smoke-test:live` failure after bumping `@se-studio/*` | **core** — fix package behaviour | **Stop.** Switch to core-first or set `blocked_on: "@se-studio/<pkg>@<version>"`. Customer only bumps after npm publish. |
+| Discovery smoke (`llms.txt`, `markdown-index.txt`, `cms.txt`, `site-info.md`) origin mismatch on `*.vercel.app` | **core** — `@se-studio/site-check` (`discovery.urlOrigin`) | **Refuse** per-request origin hacks (`getRequestBaseUrl`, `headers()` for `baseUrl`). Bump `site-check@2.9.4+`. |
+| Patching `@se-studio/site-check` expectations in app code | **core** `site-check` | **Refuse.** Open core PR + changeset. |
+| Forking converter / link logic already in `contentful-rest-api` | **core** | **Refuse.** Fix converter or API in core. |
+| `pnpm patch`, `patchedDependencies`, or overrides to fork `@se-studio/*` | **forbidden** | **Refuse** (see root `AGENTS.md`). |
+| New smoke assertion that should apply to all marketing sites | **core** `site-check` | **Refuse** site-only assertion helpers; extend site-check. |
+| `route-build-policy.json` change to hide a core regression (e.g. allow new `ƒ` on CMS routes) | **core** + site routing fix | **Refuse** policy-only workaround; fix why route went dynamic. |
+
+## Allowed customer-only smoke edits
+
+| Change | When |
+|--------|------|
+| Add/remove **curated URLs** in `smoke.cases.json` | New CMS pages, article types, tags/people go live — follow `se-marketing-sites-smoke-test-setup` |
+| Set `discovery` flags to `false` | Site-specific infra (e.g. CloudFront not routing discovery paths yet) |
+| `cmsIntegrity.routing` mapping | Per-site URL calculators — not a package bug |
+| Security **probe** cases (`category: probe`) | Site-specific hardening (see brightline reference) |
+
+## `defer-extract` (escape hatch)
+
+Use only when the user **explicitly** accepts short-term customer code with a core extraction ticket:
+
+1. Manifest `placement.decision: defer-extract`
+2. `extract_to_core: pending` + `extract_rationale` (what moves to which package)
+3. Add `work/tracker.yaml` rollout or `attention` item if multi-site
+4. **Do not** merge to customer `develop` if it blocks other sites on a shared package fix
+
+## Manifest gate
+
+Before committing customer changes to any of:
+
+- `smoke.cases.json`, `route-build-policy.json`
+- `src/lib/server-config.ts`, discovery route handlers (`llms.txt`, `markdown-index.txt`, …)
+- `scripts/smoke-test-*.ts`, `.github/workflows/deployment-smoke.yml`
+
+…when the **stated goal** is “fix deploy smoke” or “fix site-check failure”:
+
+1. Record `placement.decision` and `placement.rationale` in `work/active/<feature>.yaml`
+2. If decision is `core`: **do not commit customer workaround** — switch mode
+3. If decision is `customer`: user must confirm in chat (legitimate site-only URL curation)
+4. If decision is `defer-extract`: user must confirm extraction plan in chat
+
+## Emergency bypass (temporary only)
+
+- `SMOKE_TEST_IGNORE=true` on a single deploy
+- `workflow_dispatch` deployment smoke against a known-good URL
+- Skip Vercel Deployment Check with **human** approval
+
+Never treat emergency bypass as permission to land a permanent customer patch for `@se-studio/*` behaviour.

package/references/agent-session/smoke-deploy-failure-playbook.md

@@ -0,0 +1,80 @@
+# Smoke / deploy failure playbook
+
+When **local smoke**, **`smoke-test:live`**, or **Vercel Deployment Checks** fail, follow this sequence. Do **not** patch customer origin/URL logic to satisfy `@se-studio/site-check` assertions.
+
+Full refusal rules: [`refuse-customer-patches.md`](./refuse-customer-patches.md).
+
+## 1. Classify the failure
+
+Read the failing step and package:
+
+| Failure mentions | Likely owner |
+|------------------|--------------|
+| `discovery`, `llms.txt`, `markdown-index.txt`, `urlOrigin`, canonical origin | `@se-studio/site-check` |
+| `article link integrity`, `cmsIntegrity` | `@se-studio/site-check` + site `routing` config (customer OK) or `contentful-rest-api` (core) |
+| `route-build-policy`, `mustBeSsgOrStatic`, `ƒ` on CMS route | Site introduced dynamic APIs — fix site routing/layout **or** core if shared helper caused it |
+| HTML 404/500 on a **curated** smoke path | Site content/routing or CMS — usually **customer** |
+| Lockfile / install on Vercel | Customer lockfile sync — see `lockfile-sync` reference, not site-check |
+
+## 2. If `@se-studio/*` behaviour is wrong → core-first
+
+1. Set manifest `mode: core-first` (or stop and ask user to switch).
+2. Fix in `packages/<pkg>/`, add **changeset**, run package tests.
+3. Push `dev` → wait for CI npm publish.
+4. Add/update `work/tracker.yaml` **rollout** for customer bumps.
+5. Set customer manifest `blocked_on: "@se-studio/<pkg>@<version>"` until npm confirms.
+
+**Customer repo during wait:** only dependency bump via `pnpm update` — no `baseUrl` / origin / assertion hacks.
+
+## 3. If site content/routing is wrong → site-first
+
+Examples: wrong slug in `smoke.cases.json`, page unpublished, new article type needs a case.
+
+1. Confirm placement `customer`.
+2. Refresh cases from production sitemap (`se-marketing-sites-smoke-test-setup` skill).
+3. Run `pnpm smoke-test:run` locally; `pnpm smoke-test:preview` against develop preview if needed.
+
+## 4. Discovery canonical origin (known anti-pattern)
+
+**Symptom:** Deploy smoke hits `https://<project>-<hash>.vercel.app` but `llms.txt` / `markdown-index.txt` list `https://www.example.com/...` links. Smoke fails origin check.
+
+**Wrong fix (refuse):**
+
+- `getRequestBaseUrl()` from request headers in `server-config` or discovery routes
+- Rewriting discovery output to match deployment host permanently
+
+**Right fix:**
+
+1. Core: `@se-studio/site-check@2.9.4+` with `discovery.urlOrigin: auto` (default in smoke runner).
+2. Customer: `pnpm update @se-studio/site-check@2.9.4 -r`, keep canonical `baseUrl` in app config.
+3. Tracker rollout: `site-check-discovery-canonical` in `work/tracker.yaml`.
+
+## 5. Emergency unblock (human or agent with explicit approval)
+
+| Action | Use when |
+|--------|----------|
+| `workflow_dispatch` deployment smoke | Re-test after core fix + customer bump |
+| `SMOKE_TEST_IGNORE=true` | One-off deploy; document in manifest notes |
+| Human approves blocked Deployment Check | Production promotion already reviewed |
+
+Record what was bypassed and the real fix still required (core PR / npm bump).
+
+## 6. Validate before customer push
+
+| Check | Command |
+|-------|---------|
+| Local HTTP smoke | `pnpm smoke-test:run` |
+| Preview smoke | `pnpm smoke-test:preview` (develop URL + bypass token) |
+| After core bump | `pnpm update @se-studio/site-check@<version> -r` then re-run smoke |
+| Route policy | `pnpm validate:routes` when Contentful creds available in CI |
+
+Deployment checks stay **HTTP-only** — never enable `cmsIntegrity` on Vercel live smoke.
+
+## 7. Handoff
+
+Include in manifest / handoff:
+
+- Root cause (core vs customer)
+- Published package versions required
+- Tracker rollout id
+- Whether any emergency bypass was used

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

@@ -122,15 +122,36 @@ Fetch live markdown when `website.markdownAccess` is enabled: `https://<prod><pa
 
 - `people.md` — `enablePerson=false`; clinicians covered by `provider-pages.md` on Brightline
 
+## Article create pipeline (all sites)
+
+When agents build articles or long pages from an **external package** (doc, Drive, Figma, zip):
+
+```text
+task-source-readiness-review → soft-proof + light human yes
+  → task-create-from-document / task-create-article
+  → task-preview-verify (multi-block QA when relevant)
+```
+
+**Core principles** (also in `SOURCE-READINESS.md`):
+
+1. **No copy rewrite** — faithful structure only  
+2. **Source sequence** beats CMS convenience  
+3. **Do not invent pair/side-by-side layouts** unless the source is a true pair  
+4. **Placeholders** for missing art (GO-WITH-GAPS) rather than silent reordering  
+5. **Merge continuous prose** — avoid body-only section spam  
+
+Site `articles.md` must name **this site’s** body components. Do not paste SE multi-block / Case study rich text stacks onto brands that use a single Article rich text body.
+
 ## Other playbook types
 
 | File | When |
 |------|------|
-| `articles.md` / `ARTICLES.md` | Article types, tag rules, featuredImage vs visuals |
+| `articles.md` / `ARTICLES.md` | Article types, tag rules, featuredImage vs visuals, readiness pointer |
 | `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`) |
+| `case-study-from-package.md` (SE) | Optional specialized multi-block package playbook + hosted example |
 
 ## Generator behaviour
 

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

@@ -178,12 +178,14 @@ Skill: **`contentful-cms-create-editor-playbooks`**
 | 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 |
+| **Tighten** `articles.md` | Work / video / blog rules; **multi-block Case study / Blog rich text**; **source readiness** + faithful sequence (demote inventing Separated pairs); lab ports |
+| **Add** `case-study-from-package.md` + task stub | Hosted soft-proof example + package intake for work multi-block |
 | **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` |
 
+See also: `SOURCE-READINESS.md` and `examples/se-case-study-*.md` in this references folder.
+
 ### SE website editor guardrails (put in `pages.md`)
 
 - New marketing pages: clone `/about`, `/services`, or `/demo-landing` — not blank canvas
@@ -196,6 +198,10 @@ Skill: **`contentful-cms-create-editor-playbooks`**
 
 ---
 
+## PointMe note
+
+When `docs/cms-editor/pointme/` is created, add the shared **source readiness + faithful structure** paragraph to `articles.md` (see other sites’ light-touch pattern). No SE multi-block stacks.
+
 ## Per-project audit checklist
 
 Copy into working notes for each site:
@@ -209,8 +215,9 @@ Copy into working notes for each site:
 [ ] capabilities.json reviewed
 [ ] P0 playbook list approved by user
 [ ] pages.md hub links all specialized playbooks
+[ ] articles.md points at task-source-readiness-review (faithful structure, no copy rewrite)
 [ ] task stub per specialized playbook
-[ ] editor-pack regenerated
+[ ] editor-pack regenerated (after @se-studio/contentful-cms bump when new core tasks)
 [ ] project doctor clean
 [ ] pushed to develop
 ```

package/references/contentful-cms-editor-playbooks/SOURCE-READINESS.md

@@ -0,0 +1,96 @@
+# Source readiness review (generic)
+
+Canonical agent guidance for **package intake before CMS create**. Hosted MCP surfaces the short task as `cms-edit://customer/task-source-readiness-review` (from `@se-studio/contentful-cms` editor-tasks). This file is the fuller reference for playbook authors and coding agents.
+
+## Pipeline
+
+```text
+Intake → inventory → beat sheet → verdict → soft-proof → light human yes → create → preview QA
+```
+
+Never skip readiness for non-trivial external packages (Drive, Figma, multi-file zip, long brief).
+
+## Non-negotiables
+
+| Rule | Meaning |
+|------|---------|
+| **No copy rewrite** | cms-edit structures and places source text only |
+| **Sequence from design/source** | Do not invent order |
+| **No invented pairs** | Side-by-side collections only when the source is a true pair |
+| **Placeholders beat reordering** | Keep missing slots labeled |
+| **Merge continuous prose** | Don’t split body-only blocks without a layout break |
+| **Light human yes** | Accept “yes” / “go” / “proceed” |
+
+## Verdict threshold
+
+### NO-GO (any one)
+
+- Sequence unknown
+- Narrative incomplete for the content type
+- Building would invent structure (pairs, titles, order)
+- Conflicting sources with no owner decision
+
+### GO-WITH-GAPS
+
+- Sequence clear + narrative usable as written
+- Missing art **≤ 3** slots **or** **≤ ~25%** of visual beats, each named with placeholder strategy
+
+### GO
+
+- GO-WITH-GAPS plus art complete for the soft-proof (or explicit CMS asset reuse)
+
+## Artifact templates
+
+### Inventory
+
+| # | Role | Source file / ref | Status | CMS mapping |
+|---|------|-------------------|--------|-------------|
+| 1 | Hero | `hero.jpg` | ready | article `featuredImage` |
+| 2 | Product UI | — | missing | body visual + placeholder label |
+
+### Beat sheet
+
+| Order | Beat | Source | Block type | Notes |
+|-------|------|--------|------------|-------|
+| 1 | Open | Doc §1 | Body RTF | merge paras |
+| 2 | Product | `ui.png` | Body + visual | width per playbook |
+
+### Soft-proof (human yes)
+
+```text
+Verdict: GO-WITH-GAPS
+Gaps: #3 left pair art missing → labeled placeholder
+1. … 
+2. …
+Copy: unchanged from source
+```
+
+## Site playbooks
+
+When authoring `docs/cms-editor/<projectKey>/articles.md`:
+
+1. Point create-from-package flows at `task-source-readiness-review`
+2. State **faithful structure only**
+3. Describe **this site’s** body components (do not paste SE multi-block stacks onto other brands)
+4. Optionally link or embed one condensed example (hosted MCP cannot read skills package paths)
+
+## Worked examples
+
+See `examples/` in this folder:
+
+| File | Flavour |
+|------|---------|
+| `se-case-study-om1-shaped.md` | SE multi-block work, GO-WITH-GAPS |
+| `se-case-study-meet-makers-shaped.md` | SE simpler multi-block, GO |
+| `om1-resource-case-study-shaped.md` | OM1 resource URL + single body RTF |
+| `brightline-learning-hub-article-shaped.md` | Brightline learning hub |
+| `pedestal-publication-shaped.md` | Pedestal publication |
+| `headwater-news-shaped.md` | Headwater news (GO vs thin NO-GO) |
+
+## Anti-patterns
+
+- Defaulting every two images to a pair/side-by-side collection
+- Rewriting client copy “for tone”
+- Dropping missing art and renumbering
+- One body block per paragraph with no visual between (gappy section shells on some sites)
+- Building before soft-proof + yes on a multi-asset package

package/references/contentful-cms-editor-playbooks/examples/brightline-learning-hub-article-shaped.md

@@ -0,0 +1,48 @@
+# Example — Brightline learning hub article (readiness + tags)
+
+**Site:** Brightline · **Family:** learning hub / blog · **Verdict:** GO-WITH-GAPS
+
+## Scenario
+
+> “Turn this clinical-education brief and 2 images into a learning hub article. Follow tag matrix rules.”
+
+## Sources
+
+| Source | Notes |
+|--------|--------|
+| Editorial brief | Title + body sections |
+| 2 images | Hero + inline |
+| Tag guidance | blog-tag-matrix / site playbook |
+
+## Inventory
+
+| # | Role | Status | Mapping |
+|---|------|--------|---------|
+| 1 | Hero | ready | featuredImage |
+| 2 | Body | ready | Article body per Brightline ARTICLES playbook |
+| 3 | Inline figure | **missing** | placeholder or omit only if human says skip |
+| 4 | Tags | needs human | matrix-constrained |
+
+## Verdict
+
+**GO-WITH-GAPS** if body + hero ready and only optional inline missing with a named plan; **NO-GO** if tags/topic cannot be chosen without inventing clinical categories.
+
+## Soft-proof
+
+```text
+Verdict: GO-WITH-GAPS
+1. Hero + SEO fields from brief (no claim invention)
+2. Body RTF — source sections in order
+3. Inline image slot — placeholder or deferred
+4. Tags — proposed from matrix; human yes required
+```
+
+## What not to do
+
+- Invent tags outside matrix
+- Soften clinical language without human request
+- Clone wrong template family
+
+## Copy policy
+
+Faithful structure only; clinical tone left as provided.

package/references/contentful-cms-editor-playbooks/examples/headwater-news-shaped.md

@@ -0,0 +1,48 @@
+# Example — Headwater news (GO vs thin NO-GO)
+
+**Site:** Headwater Science · **Type:** news · **Verdicts:** GO or NO-GO
+
+## Scenario A — GO
+
+> “Publish this press note: full short body (3 paras), date, logo/hero.”
+
+### Inventory
+
+| # | Role | Status |
+|---|------|--------|
+| 1 | Headline + body | ready |
+| 2 | Date | ready |
+| 3 | Hero/logo | ready |
+
+### Soft-proof
+
+```text
+Verdict: GO
+1. News article type + slug
+2. Title/date/description from source
+3. Body RTF — three paras as written
+4. featuredImage
+```
+
+## Scenario B — NO-GO
+
+> “Make a news post from this one-line LinkedIn blurb and no assets.”
+
+### Why NO-GO
+
+- Narrative incomplete (no usable body)
+- No art and no permission to ship without
+- Building would invent paragraphs
+
+### Agent response
+
+Stop. List blockers. Do not invent body copy. Ask for full release text or explicit human-written draft.
+
+## What not to do
+
+- Expand a one-liner into a fake press release
+- Borrow SE case-study multi-block patterns
+
+## Copy policy
+
+Only structure what was given.

package/references/contentful-cms-editor-playbooks/examples/om1-resource-case-study-shaped.md

@@ -0,0 +1,52 @@
+# Example — OM1 resource case study (single body, readiness still applies)
+
+**Site:** OM1 · **URL family:** `/resources/case-studies/{topic}/{slug}/` · **Verdict:** GO
+
+OM1 does **not** use SE multi-block CSRT stacks. Body is typically **one Article rich text** (+ optional quote/callout). Readiness still runs so agents don’t invent structure or rewrite.
+
+## Scenario
+
+> “Create a case study article from this approved PDF/narrative and hero image. Topic tag AI.”
+
+## Sources
+
+| Source | Notes |
+|--------|--------|
+| Approved narrative PDF/doc | Full article copy |
+| Hero landscape | featuredImage |
+| Primary topic | `ai` (must match URL segment) |
+| Clone ref | Existing case-studies article from playbook |
+
+## Inventory
+
+| # | Role | Status | Mapping |
+|---|------|--------|---------|
+| 1 | Hero | ready | `featuredImage` |
+| 2 | Body | ready | Article rich text (single) |
+| 3 | Authors | ready | Person links |
+| 4 | Primary tag | ready | drives `{topic}` |
+
+## Verdict
+
+**GO** — narrative complete, hero present, topic decided. No multi-ART invent.
+
+## Soft-proof
+
+```text
+Verdict: GO
+1. [template] Article hero fields from entry
+2. Article rich text — full body from doc (as written)
+3. Optional quote only if present in source
+Slug/topic/type per resource-article-pages playbook
+```
+
+## What not to do
+
+- Import SE “Case study rich text” multi-block pattern
+- Invent Separated visuals
+- Rewrite clinical claims
+- Wrong primary tag (breaks URL)
+
+## Copy policy
+
+Unchanged; structure into one body RTF (+ embeds only if source has them).

package/references/contentful-cms-editor-playbooks/examples/pedestal-publication-shaped.md

@@ -0,0 +1,50 @@
+# Example — Pedestal publication (poster + download fields)
+
+**Site:** Pedestal Health · **Type:** publications · **Verdict:** GO
+
+## Scenario
+
+> “Add this publication: title, abstract, poster image, and PDF download.”
+
+## Sources
+
+| Source | Notes |
+|--------|--------|
+| Title + abstract | From publisher brief |
+| Poster image | Landscape/portrait per playbook |
+| PDF file | Download asset |
+| Clone ref | Recent publication from playbook |
+
+## Inventory
+
+| # | Role | Status | Mapping |
+|---|------|--------|---------|
+| 1 | Listing/hero art | ready | featuredImage / poster field per playbook |
+| 2 | Abstract | ready | summary / body fields as site defines |
+| 3 | PDF | ready | download / media field |
+| 4 | Tags/type | ready | publications type + routing |
+
+## Verdict
+
+**GO** when PDF + poster + abstract present. **NO-GO** if PDF missing and playbook requires download (don’t fake a link).
+
+## Soft-proof
+
+```text
+Verdict: GO
+1. Article type publications + slug
+2. Fields: title, date, description from abstract (no rewrite)
+3. Poster / featured image
+4. PDF asset linked
+5. Body only if playbook expects more than abstract
+```
+
+## What not to do
+
+- Invent abstract from title alone
+- Skip PDF and ship empty download
+- Apply SE multi-block case-study layout
+
+## Copy policy
+
+Abstract and titles as provided.

package/references/contentful-cms-editor-playbooks/examples/se-case-study-meet-makers-shaped.md

@@ -0,0 +1,51 @@
+# Example — SE case study (Meet the Makers–shaped, GO)
+
+**Site:** SE Studio · **Type:** work · **Verdict:** GO
+
+Smaller multi-block set; good first lab target. Production public path pattern: `/work/{client}/{title-slug}/` (lab: `lab/…`).
+
+## Scenario
+
+> “Port this simpler case study multi-block for lab. Faithful art order; don’t invent pairs.”
+
+## Sources
+
+| Source | Notes |
+|--------|--------|
+| Ordered image list from human / Figma | Clear sequence |
+| Short narrative | Intro, process, outcome |
+| Existing assets in CMS or Drive | All present |
+
+## Inventory (excerpt)
+
+| # | Role | Status | Mapping |
+|---|------|--------|---------|
+| 1 | Hero | ready | featuredImage |
+| 2 | Intro copy | ready | CSRT body (merge) |
+| 3 | Maker portraits sequence | ready | CSRT visuals or Visuals only if design is a grid |
+| 4 | Closing copy | ready | CSRT body |
+
+## Verdict
+
+**GO** — sequence known, art complete, copy usable as written.
+
+## Soft-proof
+
+```text
+Verdict: GO
+1. Hero (template)
+2. CSRT body — intro
+3. CSRT visual / stacked media per design (not inventing Separated)
+4. CSRT body — close
+Lab flags on
+```
+
+## What not to do
+
+- Force Separated because “there are two portraits”
+- Add section headings the source doesn’t have
+- Touch production entry — always new lab draft
+
+## Copy policy
+
+Unchanged from source.

package/references/contentful-cms-editor-playbooks/examples/se-case-study-om1-shaped.md

@@ -0,0 +1,70 @@
+# Example — SE case study from package (OM1-shaped, GO-WITH-GAPS)
+
+**Site:** SE Studio (`se2026`) · **Type:** work case study · **Verdict used:** GO-WITH-GAPS
+
+Synthetic package shaped like a real multi-block work port (Drive zip + Figma sequence + narrative). Names are illustrative.
+
+## Scenario
+
+> “Build a lab case study from this Drive folder and the Figma OM1 frame. Keep copy as written.”
+
+## Sources provided
+
+| Source | Notes |
+|--------|--------|
+| Figma frame (ordered art direction) | Sequence + pair moments + widths |
+| Drive zip (~11 files) | Photos, UI grabs, 2 decorative videos |
+| Narrative doc | Origin → challenge → approach → close |
+| Production ref | Other SE work pieces for hero/template only |
+
+## Inventory (excerpt)
+
+| # | Role | File | Status | Mapping |
+|---|------|------|--------|---------|
+| 1 | Hero | `OM1_Hero.jpg` | ready | article `featuredImage` |
+| 2 | Website UI | `OM1_websiteImage.png` | ready | CSRT `visual` ~80% |
+| 3L | Pair left | — | **missing** | Separated left + **placeholder** |
+| 3R | Pair right | `OM1_BlueModel.jpg` | ready | Separated right |
+| 4 | Origin copy | Doc §1–2 | ready | CSRT body only (merge paras) |
+| 5 | Hands photo | `OM1_HandsWithScreen.jpg` | ready | CSRT visual 100% |
+| 6L | Pair left | `OM1_ManAndPatterns.jpg` | ready | Separated left |
+| 6R | Pair right dialogs | — | **missing** | Separated right + **placeholder** |
+| 7 | Challenge copy | Doc §3 | ready | CSRT body only |
+| 8 | Landscape demo | `…LandscapeBlue….mp4` | ready | CSRT visual; autoplay+loop |
+| … | … | … | … | … |
+
+## Verdict
+
+**GO-WITH-GAPS** — sequence clear from Figma; narrative complete; **2 missing visual slots** (≤3), each placeholder-labeled. Do not invent substitute art or drop slots.
+
+## Soft-proof (structure only; copy unchanged)
+
+```text
+Verdict: GO-WITH-GAPS
+1. [template] Article hero — title/subtitle from doc; featuredImage hero
+2. CSRT media — website UI 80%
+3. Separated visuals — placeholder left | blue model right
+4. CSRT body — origin paras (merged)
+5. CSRT media — hands 100%
+6. Separated — man/patterns | placeholder dialogs
+7. CSRT body — challenge
+8. CSRT media — landscape video autoplay+loop ~70%
+9. CSRT body — approach
+10. CSRT media — mobile screens
+11. Quote — as in source
+12. Separated or CSRTs — pattern | orange demo (only if Figma is a true pair)
+13. CSRT body — close
+Lab: slug lab/…, hidden, unindexed
+```
+
+## What not to do
+
+- Invent Separated for stacked single images
+- Rewrite narrative “for flow”
+- Reorder to put all text first
+- Use article `visuals` as a dump for body art
+- Skip placeholders and renumber
+
+## Copy policy
+
+**Unchanged.** Meta `description` drafted from existing claims only; human **yes** on soft-proof.

package/references/deployment-smoke-feature-branch-skip/README.md

@@ -0,0 +1,66 @@
+# Deployment smoke — skip on feature branches
+
+Vercel **Deployment Checks** wait for a GitHub status from the smoke workflow. On feature-branch previews the `smoke` job `if` excludes the branch, so **no job runs and no status is posted** — Vercel stays on "Waiting for checks" and the PR blocks.
+
+**Fix:** add a `skip-smoke-outside-integration-branches` job that posts **success** when the deploy ref is not an integration/production branch. Real smoke still runs only on integration preview + production.
+
+## Requirements
+
+1. Workflow file must exist on the repo **default branch** (`develop`, `dev`, or registry override) — `repository_dispatch` runs workflows from default branch, not the feature branch.
+2. `permissions.statuses: write` on the workflow.
+3. `CHECK_NAME` must match the status name registered in Vercel → Settings → Deployment Checks (exact string).
+4. `smoke` job `if` must already limit runs to integration + production (do not run smoke on feature branches).
+
+## Integration branch names
+
+| Repo type | Preview smoke ref | Production smoke ref |
+|-----------|-------------------|----------------------|
+| Most customer sites | `develop` | `main` |
+| HopSkipDrive extended-port | `extended-port` | `main` (if production checks enabled) |
+| se-core-product apps | `dev` | `main` |
+
+Use `client_payload.git.ref` (branch name, not `refs/heads/...` — verify per project in a test dispatch).
+
+## Copy-paste
+
+See [`workflow-snippet.yml`](workflow-snippet.yml). One skip job per Vercel project / workflow file (monorepos with multiple marketing apps need one skip job each).
+
+## cms-edit host (optional)
+
+Feature-branch PRs also trigger cms-edit Vercel projects. Skip builds outside integration branches via `ignoreCommand` in `cms-edit/host/vercel.json`:
+
+```json
+"ignoreCommand": "if [ \"$VERCEL_GIT_COMMIT_REF\" != \"develop\" ] && [ \"$VERCEL_GIT_COMMIT_REF\" != \"main\" ]; then exit 0; fi; git diff HEAD^ HEAD --quiet -- . ../ ../../pnpm-lock.yaml ../../pnpm-workspace.yaml ../../package.json || exit 1; exit 0"
+```
+
+Replace `develop` with your integration branch (e.g. `extended-port`).
+
+## Rollout status
+
+| Repo | Skip job on feature branches | cms-edit ignore |
+|------|------------------------------|-----------------|
+| brightline-sites | done (both apps) | done |
+| se-website-2026 | pending → M4 branch | pending |
+| om1-website | audit | audit |
+| pedestal-sites | audit | audit |
+| pointme | audit | audit |
+| hsd-extended-port | audit | n/a |
+
+Update this table when applying the pattern.
+
+## Emergency unblock (one PR)
+
+If the skip job is not yet on default branch, post success manually:
+
+```bash
+gh api "repos/<owner>/<repo>/statuses/<commit-sha>" \
+  -f state=success \
+  -f context="Vercel - <project-name>: deployment smoke" \
+  -f description="Skipped — deployment smoke runs only on develop and main"
+```
+
+## Verify
+
+1. Merge skip job to default branch.
+2. Open a feature PR — Vercel preview should complete without pending deployment smoke.
+3. Push to `develop` — deployment smoke should run and gate aliasing as before.

package/references/deployment-smoke-feature-branch-skip/workflow-snippet.yml

@@ -0,0 +1,38 @@
+# Add BEFORE the smoke job in each deployment-smoke workflow.
+# Replace <vercel-project-name> and integration/production refs as needed.
+
+jobs:
+  skip-smoke-outside-integration-branches:
+    if: |
+      github.event_name == 'repository_dispatch' &&
+      github.event.client_payload.project.name == '<vercel-project-name>' &&
+      github.event.client_payload.git.ref != 'develop' &&
+      github.event.client_payload.git.ref != 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Skip deployment smoke on feature branches
+        env:
+          CHECK_NAME: 'Vercel - <vercel-project-name>: deployment smoke'
+          DEPLOYMENT_SHA: ${{ github.event.client_payload.git.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api "repos/${GITHUB_REPOSITORY}/statuses/${DEPLOYMENT_SHA}" \
+            -f state=success \
+            -f context="${CHECK_NAME}" \
+            -f description="Skipped — deployment smoke runs only on develop and main" \
+            -f target_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+  smoke:
+    if: |
+      (github.event_name == 'workflow_dispatch') ||
+      (
+        github.event_name == 'repository_dispatch' &&
+        github.event.client_payload.project.name == '<vercel-project-name>' &&
+        (
+          (github.event.client_payload.git.ref == 'develop' &&
+           github.event.client_payload.environment == 'preview') ||
+          (github.event.client_payload.git.ref == 'main' &&
+           github.event.client_payload.environment == 'production')
+        )
+      )
+    # ... existing smoke steps unchanged ...

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

@@ -1,8 +1,8 @@
 {
   "canonicalPatchesScript": "~/source/se/se-core-product/scripts/check-no-pnpm-patches.mjs",
   "pinOverrides": {
-    "next": "^15.5.19",
-    "@types/node": "^24.13.2"
+    "next": "^15.5.21",
+    "@types/node": "^24.13.3"
   },
   "pnpm": {
     "major": 11,
@@ -72,8 +72,7 @@
       "displayName": "HopSkipDrive Extended Port",
       "path": "~/source/customers/hopskipdrive/hsd-extended-port",
       "branch": "extended-port",
-      "wip": true,
-      "wipNote": "Parity port from legacy GraphQL/Netlify site onto @se-studio packages. Work on extended-port only — not develop/production. Defer routine deps bumps until parity snags are under control unless explicitly requested.",
+      "wipNote": "Parity port complete (2026-07-07). Work on extended-port only — not develop/production until cutover. Rollouts tracked in work/tracker.yaml.",
       "validate": "pnpm validate",
       "workspace": false,
       "hasPinOverrides": false

package/references/lockfile-sync/README.md

@@ -48,7 +48,8 @@ Apply the full stack when touching deps or CI in each repo:
 | brightline-sites | yes | yes | yes | yes |
 | pedestal-sites | — | partial | — | no |
 | om1-website | — | — | — | — |
-| se-website-2026 | — | — | — | — |
+| se-website-2026 | yes | yes | yes | yes |
 | pointme | — | — | — | — |
+| hsd-extended-port | yes | yes (extended-port) | n/a | yes |
 
 Update this table as repos adopt the pattern.

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

@@ -11,8 +11,10 @@ Use this skill when a customer site needs **hosted MCP editor playbooks** — th
 
 | File | Purpose |
 |------|---------|
-| `.agents/references/contentful-cms-editor-playbooks/PATTERNS.md` | Two-file pattern, sections, naming, Brightline examples |
+| `.agents/references/contentful-cms-editor-playbooks/PATTERNS.md` | Two-file pattern, sections, naming, Brightline examples, article create pipeline |
 | `.agents/references/contentful-cms-editor-playbooks/PROJECT-ROLLOUT.md` | Rollout queue (Pedestal → OM1 → PointMe → SE website) and per-site audit hints |
+| `.agents/references/contentful-cms-editor-playbooks/SOURCE-READINESS.md` | Package intake, GO / GO-WITH-GAPS / NO-GO, faithful structure (no copy rewrite) |
+| `.agents/references/contentful-cms-editor-playbooks/examples/` | Worked input packages (SE, OM1, Brightline, Pedestal, Headwater) |
 
 ## When to use
 
@@ -139,6 +141,18 @@ See `PATTERNS.md` for the full Brightline hub example.
 
 **Do not** put task stubs in the root — only under `tasks/`.
 
+### Articles playbooks (article-heavy sites)
+
+When writing or tightening `articles.md` / `ARTICLES.md`:
+
+1. Point external package creates at **`task-source-readiness-review`** (core task from `@se-studio/contentful-cms`)
+2. State **faithful structure only — do not rewrite source copy**
+3. Composition follows **source sequence**; do **not** invent pair/side-by-side layouts unless the design is a true pair
+4. Name **this site’s** body components only (never paste SE Case study rich text multi-block onto other brands)
+5. Optional: one condensed example or link to a specialized package playbook for high-traffic types
+
+See `SOURCE-READINESS.md` and `examples/`.
+
 ### Specialized playbook sections
 
 Each `<topic>.md` should include:

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

@@ -56,6 +56,8 @@ Example `package.json` entries:
 
 **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.
 
+**Feature branches must not run smoke** — limit the `smoke` job to integration preview (`develop` + `preview`) and production (`main` + `production`). Feature-branch previews still fire `repository_dispatch`; without a matching job, Vercel waits forever on "Waiting for checks". Add a `skip-smoke-outside-integration-branches` job that posts **success** for non-integration refs. Full rollout guide: [`references/deployment-smoke-feature-branch-skip/`](../../references/deployment-smoke-feature-branch-skip/README.md). Monorepos: one skip job per Vercel project workflow. Non-`develop` integration branches (e.g. HSD `extended-port`): adjust ref checks in both jobs.
+
 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
@@ -67,11 +69,45 @@ on:
     types:
       - vercel.deployment.ready
 
+permissions:
+  contents: read
+  actions: read
+  statuses: write
+
 jobs:
-  smoke:
+  skip-smoke-outside-integration-branches:
     if: |
+      github.event_name == 'repository_dispatch' &&
       github.event.client_payload.project.name == '<vercel-project-name>' &&
-      github.event.client_payload.environment == 'production'
+      github.event.client_payload.git.ref != 'develop' &&
+      github.event.client_payload.git.ref != 'main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Skip deployment smoke on feature branches
+        env:
+          CHECK_NAME: 'Vercel - <vercel-project-name>: deployment smoke'
+          DEPLOYMENT_SHA: ${{ github.event.client_payload.git.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh api "repos/${GITHUB_REPOSITORY}/statuses/${DEPLOYMENT_SHA}" \
+            -f state=success \
+            -f context="${CHECK_NAME}" \
+            -f description="Skipped — deployment smoke runs only on develop and main" \
+            -f target_url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+
+  smoke:
+    if: |
+      (github.event_name == 'workflow_dispatch') ||
+      (
+        github.event_name == 'repository_dispatch' &&
+        github.event.client_payload.project.name == '<vercel-project-name>' &&
+        (
+          (github.event.client_payload.git.ref == 'develop' &&
+           github.event.client_payload.environment == 'preview') ||
+          (github.event.client_payload.git.ref == 'main' &&
+           github.event.client_payload.environment == 'production')
+        )
+      )
     runs-on: ubuntu-latest
     steps:
       - uses: vercel/repository-dispatch/actions/checkout@v1
@@ -377,6 +413,24 @@ Commit `route-build-policy.json` beside `smoke.cases.json`. Start from `@se-stud
 
 **HubSpot bootstrap:** use `createHubSpotBootstrapScript()` with no args in root layout — not `headers()` + middleware pathname.
 
+## Deploy / live smoke failure playbook
+
+When **`pnpm smoke-test:live`**, Vercel Deployment Checks, or preview smoke fail after a dependency bump, **do not** patch customer `baseUrl`/origin logic to satisfy `@se-studio/site-check`.
+
+**Playbook:** [`packages/skills/references/agent-session/smoke-deploy-failure-playbook.md`](../../references/agent-session/smoke-deploy-failure-playbook.md)
+
+**Refusal rules:** [`packages/skills/references/agent-session/refuse-customer-patches.md`](../../references/agent-session/refuse-customer-patches.md) (agent-session Step 3b)
+
+Quick sequence:
+
+1. **Classify** — discovery/origin → `site-check`; broken slug → customer `smoke.cases.json`; new `ƒ` route → fix dynamic APIs.
+2. **Core-first** if package behaviour is wrong — changeset, push `dev`, tracker rollout, customer `blocked_on` until npm.
+3. **Customer-only** if curating URLs — refresh from sitemap; one case per **enabled** article-type segment.
+4. **Discovery canonical origin** — bump `site-check@2.9.4+`; never add `getRequestBaseUrl()` (tracker rollout `site-check-discovery-canonical`).
+5. **Emergency** — `SMOKE_TEST_IGNORE` or `workflow_dispatch` smoke; not a permanent site patch.
+
+Record `placement.decision` in manifest before smoke/server-config commits aimed at unblocking deploy.
+
 ## Reference
 
 - HTTP + integrity example: `apps/example-empty/smoke.cases.json` and `scripts/smoke-test-run.ts` (monorepo).

package/skills/site-workflows-agent-session/SKILL.md

@@ -78,6 +78,16 @@ If the user works only in a customer repo with no core checkout, still create/up
 
 **One feature = one manifest.** Do not append unrelated work to an existing manifest.
 
+### Cross-site tracker (`work/tracker.yaml`)
+
+For work that spans repos (core npm rollouts, deployment gates, “bump on all sites”):
+
+1. Add or update a `rollouts` entry in `work/tracker.yaml` when a `@se-studio/*` release needs customer adoption
+2. Add `attention` items for human-only gates (blocked Vercel deploy, hosted MCP smoke, merge decisions)
+3. Run `pnpm work:tracker` from se-core-product to refresh `work/TRACKER.md`
+
+Humans glance at **`work/TRACKER.md`** for the dashboard; agents edit `tracker.yaml` + manifests.
+
 ---
 
 ## Step 3 — Placement checklist (before non-trivial code)
@@ -105,6 +115,25 @@ Run before implementing anything beyond a one-line fix. Record results in manife
 
 **Core-first guard:** If checklist says `customer`, implement in customer repo (read-only probe in core example apps only if useful).
 
+### Step 3b — Refuse customer patches (mandatory)
+
+After the placement checklist, run the **refusal table** when the task involves deploy smoke, `smoke.cases.json`, discovery routes, `server-config`, or “fix site-check / unblock Vercel.”
+
+**Reference:** [`packages/skills/references/agent-session/refuse-customer-patches.md`](../../references/agent-session/refuse-customer-patches.md)
+
+| If the fix would… | Agent must |
+|-------------------|------------|
+| Patch `@se-studio/*` behaviour in the customer repo | **Refuse** — core-first + changeset |
+| Add `getRequestBaseUrl` or per-request origin for discovery smoke | **Refuse** — bump `@se-studio/site-check@2.9.4+` (`discovery.urlOrigin: auto`) |
+| Change `route-build-policy.json` only to hide a new `ƒ` CMS route | **Refuse** — fix dynamic usage (Biome / layout) |
+| Add curated URLs or site-only probe cases | **Allow** — placement `customer`; follow smoke-test skill |
+
+**Deploy / live smoke failed?** Follow [`smoke-deploy-failure-playbook.md`](../../references/agent-session/smoke-deploy-failure-playbook.md) — classify failure → core vs customer → `blocked_on` if waiting on npm. Emergency: `SMOKE_TEST_IGNORE` or human Deployment Check approval — **not** permanent site hacks.
+
+**Manifest gate:** Before committing customer changes to smoke config, discovery routes, or `server-config` for deploy-smoke goals, record `placement.decision` in `work/active/<feature>.yaml`. If `core`, do not commit customer workaround.
+
+**`defer-extract`:** Only when the user explicitly approves in chat. Set `extract_to_core: pending` + rationale; add tracker rollout if multi-site.
+
 ---
 
 ## Step 4 — Git isolation
@@ -274,6 +303,6 @@ Agent must load this skill, write manifest, run placement checklist, confirm bra
 | `om1` | `develop` | customer |
 | `pointme` | `develop` | customer |
 | `pedestal` | `develop` | customer monorepo |
-| `hsd-extended-port` | `extended-port` | customer (WIP) |
+| `hsd-extended-port` | `extended-port` | customer |
 
 Full paths and MCP keys: `projects.registry.json`.

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

@@ -51,11 +51,11 @@ Run that locally **before push** whenever `package.json`, lockfile, or overrides
 | `om1` | OM1 Website | `develop` |
 | `pointme` | PointMe Marketing Site | `develop` |
 | `pedestal` | Pedestal Sites | `develop` |
-| `hsd-extended-port` | HopSkipDrive Extended Port **(WIP)** | `extended-port` |
+| `hsd-extended-port` | HopSkipDrive Extended Port | `extended-port` |
 
 User may name a key (`update deps in om1`) or ask to run through all projects sequentially.
 
-**WIP:** `hsd-extended-port` is an active parity port — branch `extended-port`, not `develop`. Prefer standards alignment and targeted `@se-studio/*` catch-up over full `pnpm update -r --latest` until the snag list is stable.
+**HSD extended-port:** Parity complete (2026-07-07). Branch `extended-port`, not `develop`, until production cutover. Rollouts tracked in `work/tracker.yaml` — prefer targeted `@se-studio/*` bumps per rollout before full `pnpm update -r --latest`.
 
 ---