@se-studio/skills 1.5.8 → 1.5.11

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 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).
+
 ## 1.5.8
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.5.8",
+  "version": "1.5.11",
   "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

@@ -13,13 +13,7 @@
       "branch": "dev",
       "type": "core",
       "validate": "pnpm validate",
-      "exampleApps": [
-        "example-om1",
-        "example-se2026",
-        "example-brightline",
-        "example-brightlifekids",
-        "example-empty"
-      ]
+      "exampleApps": ["example-empty", "cms-edit-host"]
     },
     {
       "key": "se2026",

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-cms-guidelines/README.md

@@ -70,7 +70,7 @@ Invoke the skill with:
 **Example: merge only**
 
 ```bash
-cms-merge-guidelines --app-dir apps/example-om1
+cms-merge-guidelines --app-dir apps/example-empty
 ```
 
 ---

package/references/contentful-cms-cms-guidelines/variant-loop.md

@@ -51,7 +51,7 @@ or manually follow the steps below.
 ## Cursor agent task
 
 **Assign this task to a Cursor subagent.** Provide:
-- `apps/example-brightline/src/project/components/<TypeName>.tsx` (component source)
+- `<app-dir>/src/project/components/<TypeName>.tsx` (e.g. `apps/example-empty` or a customer app path)
 - `generated/cms-discovery/field-list.json` (field metadata including enum values)
 - `generated/cms-discovery/theme-context.md` (palette + typography — authoritative colour names)
 - `scripts/guidelines/variant-proposal-prompt.md` (variant proposal instructions)
@@ -121,7 +121,7 @@ Example for Hero:
 ### 2 — Capture screenshots
 
 ```bash
-# From apps/example-brightline
+# From the target app directory (e.g. apps/example-empty)
 node scripts/guidelines/capture-screenshots.mjs --variants /tmp/hero-variants.json
 ```
 

package/references/lockfile-sync/README.md

@@ -0,0 +1,54 @@
+# Lockfile sync enforcement
+
+Keep `pnpm-lock.yaml` aligned with every `package.json` and `pnpm-workspace.yaml` change.
+
+## Layers
+
+| Layer | What it catches |
+|-------|-----------------|
+| **Pre-commit** | Manifest changed without staged lockfile; default frozen install drift |
+| **CI validate** | Frozen install on integration branch (`develop` / `dev`) and PRs |
+| **CI hoisted job** | cms-edit Vercel path (`--config.node-linker=hoisted`) — platform optional deps |
+| **Vercel installCommand** | `--frozen-lockfile` on marketing sites; hoisted + frozen on cms-edit host |
+
+## Scripts (copy from se-core-product `scripts/`)
+
+- `check-lockfile-sync.sh` — full (`default` + `hoisted`) or `--quick` (default only)
+- `pre-commit-lockfile.sh` — wire into `.husky/pre-commit` before lint-staged
+
+## CI snippet
+
+See [`validate-workflow-snippet.yml`](validate-workflow-snippet.yml). Customer monorepos should:
+
+1. Run validate on **`develop`** (or your integration branch), not only `main`.
+2. Add a parallel `lockfile-hoisted` job when `cms-edit/host/.npmrc` has `node-linker=hoisted`.
+
+## Vercel
+
+| Project type | installCommand |
+|--------------|----------------|
+| Marketing app (monorepo root install) | `cd ../.. && pnpm install --frozen-lockfile` |
+| cms-edit host | `cd ../.. && pnpm install --frozen-lockfile --config.node-linker=hoisted` |
+
+## After dependency changes
+
+```bash
+pnpm install                    # repo root — never pnpm install -r for lockfile refresh
+git add package.json pnpm-lock.yaml pnpm-workspace.yaml
+```
+
+Use `pnpm install --no-frozen-lockfile` only when intentionally repairing the lockfile.
+
+## Rollout status (customer repos)
+
+Apply the full stack when touching deps or CI in each repo:
+
+| Repo | Pre-commit | CI develop/dev | CI hoisted | Vercel frozen (marketing) |
+|------|------------|----------------|------------|---------------------------|
+| brightline-sites | yes | yes | yes | yes |
+| pedestal-sites | — | partial | — | no |
+| om1-website | — | — | — | — |
+| se-website-2026 | yes | yes | yes | yes |
+| pointme | — | — | — | — |
+
+Update this table as repos adopt the pattern.

package/references/lockfile-sync/validate-workflow-snippet.yml

@@ -0,0 +1,32 @@
+# Append to .github/workflows/validate.yml (or equivalent CI workflow).
+# Run on the integration branch (develop / dev), not only main.
+
+on:
+  push:
+    branches: [main, develop] # or [main, dev] for se-core-product consumers
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm validate
+
+  # Required when cms-edit/host (or apps/cms-edit-host) uses node-linker=hoisted.
+  lockfile-hoisted:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --config.node-linker=hoisted

package/skills/contentful-cms-generate-cms-guidelines/SKILL.md

@@ -48,7 +48,7 @@ Guidelines are only meaningful when the showcase is populated with realistic dat
 
 | Input | Description |
 |---|---|
-| **App directory** | Repo-relative path, e.g. `apps/example-om1` or `apps/example-se2026` |
+| **App directory** | Repo-relative path, e.g. `apps/example-empty` in this monorepo, or an app path in a customer repo (see `docs/RELATED_PROJECTS.md`) |
 | **Mode** | `full` \| `single` \| `merge-only` |
 | **Type name** | Required for `single` mode — the exact type name from discovery, e.g. `"Hero"` or `"Cards Grid"` |
 | **Discovery URL** | `http://localhost:<PORT>/api/cms/discovery/` — `<PORT>` from the running dev server (`pnpm dev`) |

package/skills/performance-audit/SKILL.md

@@ -94,7 +94,7 @@ mkdir -p scripts
 cp node_modules/@se-studio/skills/skills/performance-audit/lighthouse.ts scripts/lighthouse.ts
 ```
 
-Or copy from `apps/example-se2026/scripts/lighthouse.ts` in the se-core-product monorepo if you have it available.
+Or copy from a customer site repo if available (e.g. `se-website-2026/scripts/lighthouse.ts`). This monorepo only ships `apps/example-empty`.
 
 **Customise `PAGES` for the project** — edit the `PAGES` array near the top of the script. Choose representative pages: homepage, a list/index page, and a detail page. Use the sitemap to identify good candidates:
 

package/skills/se-marketing-sites-cms-routes-and-appshared/SKILL.md

@@ -5,7 +5,7 @@ description: "Guide for the (cms-routes) route group and appShared pattern. Use
 
 # CMS Routes and appShared Pattern
 
-Reference apps: **example-se2026**, **example-brightline**, **example-om1**. (example-om1 uses `resources/`, `team/`, `topics/` instead of `articles/`, `people/`, `tags/`.)
+Reference app: **example-empty** (this monorepo). Customer sites with fuller route sets: see `docs/RELATED_PROJECTS.md` (e.g. OM1 uses `resources/`, `team/`, `topics/` instead of `articles/`, `people/`, `tags/`).
 
 ## Route Group: (cms-routes)
 

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

@@ -7,7 +7,7 @@ description: "Guide for creating new Next.js App Router pages and dynamic routes
 
 This guide explains how to create new pages and handle routing in the SE Core Product Next.js framework. The system uses Next.js App Router with Contentful-driven dynamic routing.
 
-Reference apps: **example-se2026**, **example-brightline**, **example-om1**.
+Reference app: **example-empty** (this monorepo). Customer implementations: see `docs/RELATED_PROJECTS.md`.
 
 ## Page Architecture
 

package/skills/se-marketing-sites-lib-cms-structure/SKILL.md

@@ -5,7 +5,7 @@ description: "Guide for the lib directory structure in SE Core Product CMS apps.
 
 # Lib Directory Structure
 
-Reference apps: **example-se2026**, **example-brightline**, **example-om1**.
+Reference app: **example-empty** (this monorepo). Customer implementations: see `docs/RELATED_PROJECTS.md`.
 
 ## File Responsibilities
 

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

@@ -52,6 +52,8 @@ Example `package.json` entries:
 }
 ```
 
+**Lockfile CI** — before deployment smoke, ensure `.github/workflows/validate.yml` runs `pnpm install --frozen-lockfile` on the integration branch (`develop` / `dev`) and PRs, plus a parallel `lockfile-hoisted` job when cms-edit uses `node-linker=hoisted`. Copy scripts and workflow snippet from [`references/lockfile-sync/`](../../references/lockfile-sync/README.md). Marketing `vercel.json` install commands must use `--frozen-lockfile`.
+
 **Vercel Deployment Check (live URL)** — GitHub Action on `vercel.deployment.ready` tests `client_payload.url` before production domains alias. Workflow must live on the repo **default branch**. Register the status `name` in Vercel → Settings → Build and Deployment → Deployment Checks.
 
 Filter on `client_payload.environment == 'production'` when Deployment Checks target production only. Vercel also dispatches for preview and custom environments (`preview`, `develop`, etc.); skip those to avoid duplicate CI runs. Use `workflow_dispatch` without an environment filter for manual smoke against any URL.
@@ -375,6 +377,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

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

@@ -37,6 +37,8 @@ pnpm install --frozen-lockfile --config.node-linker=hoisted
 
 Run that locally **before push** whenever `package.json`, lockfile, or overrides change. A mismatch surfaces as `ERR_PNPM_OUTDATED_LOCKFILE` (manifest vs lockfile specifiers).
 
+**Lockfile enforcement stack** — copy `scripts/check-lockfile-sync.sh` and `scripts/pre-commit-lockfile.sh` from se-core-product; wire pre-commit before lint-staged; add CI jobs from [`references/lockfile-sync/`](../../references/lockfile-sync/README.md). Marketing Vercel projects: `installCommand` must include `--frozen-lockfile`. Integration branch (`develop` / `dev`) must be in CI `push.branches`, not only `main`.
+
 ---
 
 ## Projects
@@ -234,6 +236,17 @@ After a successful update, you may add the patches check to the root `validate`
 
 This is optional follow-up — the skill workflow always runs the check regardless.
 
+## Optional: lockfile enforcement rollout
+
+When updating deps in a customer repo, adopt the full lockfile stack if missing:
+
+1. Copy `scripts/check-lockfile-sync.sh` and `scripts/pre-commit-lockfile.sh` from se-core-product.
+2. Add `bash scripts/pre-commit-lockfile.sh` to `.husky/pre-commit` (before lint-staged).
+3. Extend `.github/workflows/validate.yml`: integration branch in `push.branches`, parallel `lockfile-hoisted` job when cms-edit uses hoisted linker.
+4. Set marketing `vercel.json` `installCommand` to `cd ../.. && pnpm install --frozen-lockfile`.
+
+See [`references/lockfile-sync/README.md`](../../references/lockfile-sync/README.md) for the rollout table and workflow snippet.
+
 ---
 
 ## Troubleshooting