@se-studio/skills 1.5.5 → 1.5.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.5.7
+
+### Patch Changes
+
+- c29c4c8: Add `site-workflows-agent-session` skill and agent-session reference files for cross-repo work sessions, placement checklist, and parallel feature isolation.
+
+## 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

package/package.json

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

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

@@ -0,0 +1,45 @@
+## Agent session workflow
+
+**Load skill `site-workflows-agent-session` at the start of every coding session.**
+
+Default mode for this repo: **site-first**.
+
+### Branch policy
+
+- Agents may commit and push **`develop`** and **`feature/*`** only.
+- **Never** push to `main`, `master`, or production — human-only.
+- Prefer **draft PRs** to `develop` over direct pushes when `gh` is available.
+
+### Core vs customer placement
+
+Before non-trivial code, run the placement checklist (in the skill). Summary:
+
+| Belongs in… | Examples |
+|-------------|----------|
+| **This repo** (`src/project/*`, `cms-edit/**`) | Brand components, styling, site routing, editor-pack |
+| **Customer shared package** (if monorepo) | Consent/analytics shared across sites in this customer |
+| **`se-core-product`** (`@se-studio/*`) | Fixes/features needed by 2+ sites, CMS infrastructure |
+
+If the checklist says **core**, stop and switch to core-first mode — do not patch `@se-studio` behaviour in this repo.
+
+### Core release order
+
+When work depends on a new `@se-studio/*` npm release:
+
+1. Release from `se-core-product` (`dev` → CI publish)
+2. Confirm version on npm
+3. `pnpm update @se-studio/<package>@<version> -r` in this repo
+4. Then push `develop`
+
+Never hand-edit `package.json` dependency versions.
+
+### Parallel features
+
+- One feature = one `feature/<scope>/<slug>` branch
+- Use a **git worktree** when multiple features touch this repo at once
+- CMS edits: `--session <feature-slug>` (isolate cms-edit sessions)
+- Track in-flight work: manifest at `~/source/se/se-core-product/work/active/<feature>.yaml` (or `work/active/` in this repo if core checkout unavailable)
+
+### Production handoff
+
+When ready for production, agents **stop** and deliver a handoff note — they do not merge to `main`. See skill Step 8.

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

@@ -0,0 +1,32 @@
+# Copy to work/active/<feature>.yaml — one file per in-flight feature.
+# Canonical location: se-core-product/work/active/ (cross-repo visibility).
+
+feature: my-feature-slug
+mode: site-first # core-first | site-first
+project_key: om1
+primary_repo: ~/source/customers/om1/om1-website
+branch: feature/om1/my-feature-slug
+worktree: null # e.g. ~/source/worktrees/om1-my-feature-slug — required when parallel features share a repo
+integration_branch: develop
+
+related_repos:
+  - repo: se-core-product
+    path: ~/source/se/se-core-product
+    role: read-only # read-only | pending-extract | active
+
+placement:
+  decision: customer # core | customer | customer-shared | defer-extract
+  rationale: One-site hero layout tied to OM1 Figma
+  extract_to_core: null # pending | null
+  extract_rationale: null
+
+blocked_on: null # e.g. "@se-studio/core-ui@2.1.0"
+cms_session: null # set to feature slug when doing parallel CMS edits
+
+status: in_progress # in_progress | blocked | parked | ready_for_review
+started_at: 2026-07-05
+updated_at: 2026-07-05
+
+validation: []
+
+handoff: null

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

@@ -0,0 +1,86 @@
+{
+  "manifestPath": "work/active/<feature>.yaml",
+  "integrationBranches": {
+    "core": "dev",
+    "customer": "develop"
+  },
+  "branchPattern": "feature/<scope>/<short-slug>",
+  "projects": [
+    {
+      "key": "se-core-product",
+      "displayName": "SE Core Product",
+      "path": "~/source/se/se-core-product",
+      "branch": "dev",
+      "type": "core",
+      "validate": "pnpm validate",
+      "exampleApps": [
+        "example-om1",
+        "example-se2026",
+        "example-brightline",
+        "example-brightlifekids",
+        "example-empty"
+      ]
+    },
+    {
+      "key": "se2026",
+      "displayName": "SE Studio Site",
+      "path": "~/source/se/se-website-2026",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "g0pw3n92bre6",
+      "hostedMcp": "cms-edit-se-website",
+      "validate": "pnpm check && pnpm type-check"
+    },
+    {
+      "key": "brightline",
+      "displayName": "Brightline Sites",
+      "path": "~/source/customers/brightline/brightline-sites",
+      "branch": "develop",
+      "type": "customer-monorepo",
+      "sharedPackage": "@brightline/shared",
+      "contentfulSpaceIds": ["96gdpqkm7elu", "c27ds9epot4n"],
+      "hostedMcp": "cms-edit-brightline",
+      "validate": "pnpm -r validate"
+    },
+    {
+      "key": "om1",
+      "displayName": "OM1 Website",
+      "path": "~/source/customers/om1/om1-website",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "ddhe5ahaolzf",
+      "hostedMcp": "cms-edit-om1",
+      "validate": "pnpm check && pnpm type-check && pnpm validate:routes"
+    },
+    {
+      "key": "pointme",
+      "displayName": "PointMe Marketing Site",
+      "path": "~/source/customers/pointme/develop-marketing-site",
+      "branch": "develop",
+      "type": "customer",
+      "contentfulSpaceId": "alwdzgjlz5qv",
+      "contentfulEnvironment": "marketing-master-2025-04-15",
+      "validate": "pnpm check && pnpm type-check"
+    },
+    {
+      "key": "pedestal",
+      "displayName": "Pedestal Sites",
+      "path": "~/source/customers/pedestal/pedestal-sites",
+      "branch": "develop",
+      "type": "customer-monorepo",
+      "sharedPackage": "@pedestal/site-common",
+      "contentfulSpaceIds": ["h4s3ip99qawo", "fea4lj2cdgl5"],
+      "hostedMcp": ["cms-edit-pedestal", "cms-edit-headwater"],
+      "validate": "pnpm -r validate"
+    },
+    {
+      "key": "hsd-extended-port",
+      "displayName": "HopSkipDrive Extended Port",
+      "path": "~/source/customers/hopskipdrive/hsd-extended-port",
+      "branch": "extended-port",
+      "type": "customer",
+      "wip": true,
+      "validate": "pnpm validate"
+    }
+  ]
+}

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

@@ -66,6 +66,17 @@
       "validate": "pnpm -r validate",
       "workspace": true,
       "hasPinOverrides": false
+    },
+    {
+      "key": "hsd-extended-port",
+      "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.",
+      "validate": "pnpm validate",
+      "workspace": false,
+      "hasPinOverrides": false
     }
   ]
 }

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
@@ -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

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

@@ -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)

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/se-marketing-sites-smoke-test-setup/SKILL.md

@@ -7,7 +7,7 @@ description: "Set up or regenerate smoke.cases.json for local smoke tests from t
 
 Local smoke tests use curated HTTP cases in **`smoke.cases.json`**. Optionally enable **`cmsIntegrity`** for a local-only Contentful article-link check (no `cms-server` import in smoke scripts).
 
-Requires `@se-studio/site-check` **^2.6.1** when using `cmsIntegrity` or `pnpm smoke-test` with integrity enabled; **2.1.2+** for cache log audit; **2.0.0+** for HTTP-only static smoke.
+Requires `@se-studio/site-check` **^2.9.0** when using `discovery` endpoint checks; **^2.6.1** when using `cmsIntegrity` or `pnpm smoke-test` with integrity enabled; **2.1.2+** for cache log audit; **2.0.0+** for HTTP-only static smoke.
 
 Preview / `DRAFT_ONLY` Contentful access in local dev is expected and not a smoke failure. **Deployment / live smoke stays HTTP-only** — do not enable `cmsIntegrity` on Vercel deployment checks.
 
@@ -204,6 +204,12 @@ curl -sI "http://localhost:<port>/some-path.md"
 {
   "siteName": "my-app",
   "port": 3012,
+  "discovery": {
+    "llmsTxt": true,
+    "markdownIndexTxt": true,
+    "cmsTxt": true,
+    "siteInfoMd": true
+  },
   "cases": [
     { "category": "home", "label": "Home", "path": "/", "expectMarkdown": true },
     { "category": "page", "label": "About", "path": "/about/", "expectMarkdown": true },
@@ -218,6 +224,19 @@ curl -sI "http://localhost:<port>/some-path.md"
 }
 ```
 
+**Discovery endpoints** (`discovery` block) — requires `@se-studio/site-check@^2.9.0`:
+
+| Path | Flag | Checks when `true` |
+|------|------|-------------------|
+| `/llms.txt` | `llmsTxt` | 200, `text/plain`, llmstxt.org structure, spot-check Key pages `.md` links |
+| `/markdown-index.txt` | `markdownIndexTxt` | 200, same-origin `.md` URL list |
+| `/cms.txt` | `cmsTxt` | 200, `text/markdown`, mentions llms + markdown-index |
+| `/site-info.md` | `siteInfoMd` | 200, `text/markdown`, title + minimum body |
+
+Omit a key or set `true` to require the endpoint. Set `false` to skip (not a failure). **PointMe:** set all four to `false` until CloudFront routes these paths to Vercel.
+
+Add `/llms.txt`, `/markdown-index.txt`, and `/site-info.md` to `route-build-policy.json` → `mustBeSsgOrStatic` (commit beside `smoke.cases.json`).
+
 `expectHtmlStatus` requires `@se-studio/site-check@^2.7.2`. Omit for normal 2xx HTML checks.
 
 Optional `cmsIntegrity` (local only — see section below):

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

@@ -0,0 +1,279 @@
+---
+name: site-workflows-agent-session
+description: "Start and manage agent work sessions across se-core-product and customer sites. Declares work mode, feature branch, placement (core vs customer), parallel isolation, and production handoff. Load at the beginning of every coding session."
+---
+
+# Agent session workflow
+
+Orchestrates **where** to work, **where code belongs**, and **how to isolate parallel features**. Human merges to `main` / production — agents stop at handoff.
+
+**Registry:** [`packages/skills/references/agent-session/projects.registry.json`](../../references/agent-session/projects.registry.json) — repo paths, integration branches, hosted MCP keys.
+
+**Manifest template:** [`packages/skills/references/agent-session/manifest.template.yaml`](../../references/agent-session/manifest.template.yaml)
+
+**Human guide:** `docs/WORKFLOW.md` in se-core-product.
+
+---
+
+## When to load this skill
+
+Load **at the start of every coding session** — before reading code or making edits.
+
+Triggers:
+
+- User pastes a session opener (`Mode: site-first`, `Feature: …`)
+- User asks to work on a customer site or core package
+- User starts parallel work on another feature (new manifest, new branch)
+- User asks "where should this live?" (run placement checklist)
+
+---
+
+## Step 1 — Resolve session context
+
+Collect or infer:
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `mode` | Yes | `core-first` or `site-first` |
+| `feature` | Yes | Short slug, kebab-case (e.g. `om1-hero-redesign`) |
+| `project_key` | Yes | From registry (`om1`, `se-core-product`, `pedestal`, …) |
+| `primary_repo` | Yes | Absolute path from registry |
+| `branch` | Yes | `feature/<scope>/<slug>` — see naming below |
+| `worktree` | Optional | Separate checkout path when parallel features share a repo |
+
+**Default mode if unclear:** ask once. Site-specific UI/content → `site-first`. Package/framework/multi-site → `core-first`.
+
+**Branch naming:**
+
+```
+feature/<scope>/<short-slug>
+```
+
+| Scope | Example |
+|-------|---------|
+| Core work | `feature/core/search-webhook-fix` |
+| Customer site | `feature/om1/hero-redesign` |
+| Customer monorepo shared | `feature/brightline/consent-v2` |
+
+Integration branches (agents push feature branches here via PR or merge — **never `main`**):
+
+| Repo type | Integration branch |
+|-----------|-------------------|
+| `se-core-product` | `dev` |
+| Customer sites | `develop` (or registry override, e.g. `extended-port`) |
+
+---
+
+## Step 2 — Write or update manifest
+
+Path in **se-core-product** (canonical ledger for cross-repo visibility):
+
+```
+work/active/<feature>.yaml
+```
+
+Copy from `manifest.template.yaml`, fill all fields, set `status: in_progress`, `started_at` to today (ISO date).
+
+If the user works only in a customer repo with no core checkout, still create/update the manifest in se-core-product when that repo is available; otherwise create `work/active/<feature>.yaml` in the customer repo and note `manifest_location: customer` in the file.
+
+**One feature = one manifest.** Do not append unrelated work to an existing manifest.
+
+---
+
+## Step 3 — Placement checklist (before non-trivial code)
+
+Run before implementing anything beyond a one-line fix. Record results in manifest `placement:`.
+
+| Question | If yes → lean |
+|----------|----------------|
+| Will **2+ sites** need this within ~6 months? | **core** (`packages/*`) |
+| Is it CMS infrastructure (converter, shared renderer, cms-edit, search webhook)? | **core** |
+| Is it tied to **one brand** (Figma, copy, colours, one-off layout)? | **customer** (`src/project/*`) |
+| Shared only within **one customer monorepo** (e.g. `@brightline/shared`)? | **customer-shared** |
+| Bug in published `@se-studio/*` behaviour? | **core** — never fork in customer |
+
+**Outcomes** — set `placement.decision`:
+
+| Decision | Action |
+|----------|--------|
+| `core` | Edit `se-core-product` only; changeset before push to `dev`; customer waits for npm |
+| `customer` | Edit customer repo only; do not touch core |
+| `customer-shared` | Edit customer's shared package; not `@se-studio/*` |
+| `defer-extract` | Implement in customer now; set `extract_to_core: pending` + `extract_rationale` |
+
+**Site-first guard:** If checklist says `core` but mode is `site-first`, **stop** and ask whether to switch mode or record `defer-extract`.
+
+**Core-first guard:** If checklist says `customer`, implement in customer repo (read-only probe in core example apps only if useful).
+
+---
+
+## Step 4 — Git isolation
+
+### Single feature in repo
+
+```bash
+cd <primary_repo>
+git fetch origin
+git checkout -b <branch> origin/<integration-branch>
+```
+
+### Parallel features in same repo
+
+Use a **git worktree** per feature:
+
+```bash
+git worktree add <worktree-path> -b <branch> origin/<integration-branch>
+```
+
+Record `worktree` in manifest. Do not commit unrelated features on the same branch.
+
+### CMS parallel sessions
+
+When editing Contentful in parallel on the same space, use distinct cms-edit sessions:
+
+```bash
+--session <feature-slug>
+# or CONTENTFUL_CMS_SESSION=<feature-slug>
+```
+
+Record `cms_session: <feature-slug>` in manifest when doing CMS work.
+
+---
+
+## Step 5 — Work execution rules
+
+### core-first
+
+- Primary edits: `packages/*`, optionally `apps/example-*` to validate
+- Compare customer implementations **read-only** unless user approves commits there
+- Release train before customer push (see `AGENTS.md` **Client repos — wait for core**)
+
+### site-first
+
+- Primary edits: customer `src/project/*`, `cms-edit/**`, site config
+- **Do not** edit `se-core-product` unless placement is `core` and user approves mode switch
+- Consume `@se-studio/*` from npm — not monorepo workspace links
+
+### Blocked work
+
+If manifest has `blocked_on: "@se-studio/foo@1.2.3"`, do not push customer `develop` until npm publish is confirmed. Update manifest when unblocked.
+
+---
+
+## Step 6 — Validate before push
+
+Minimum per repo type (see registry `validate` for full command):
+
+| Repo | Typical |
+|------|---------|
+| se-core-product | `pnpm validate` or targeted `pnpm type-check` + tests |
+| Customer | registry `validate` field |
+
+Record commands run in manifest `validation:` before push.
+
+---
+
+## Step 7 — Push and PR policy
+
+Agents may push to:
+
+- `dev` / `develop` (via feature branch merge or direct if user prefers)
+- `feature/*` branches
+
+Agents must **never** push to `main`, `master`, or production branches.
+
+**Preferred:** open a **draft PR** targeting the integration branch:
+
+```bash
+gh pr create --base <integration-branch> --head <branch> --draft --title "<feature>: <summary>"
+```
+
+If `gh` is unavailable or user prefers direct push, push `feature/*` and note in handoff.
+
+---
+
+## Step 8 — Handoff (production-ready)
+
+When work is ready for human review / production promotion, **stop** — do not merge to `main`.
+
+1. Set manifest `status: ready_for_review`
+2. Deliver handoff using template below
+3. If core release was part of the work, list published package versions needed for customer bump
+
+### Handoff template
+
+```markdown
+## Handoff: <feature>
+
+**Mode:** <core-first | site-first>
+**Manifest:** work/active/<feature>.yaml
+
+### Repos and branches
+- <repo>: `<branch>` → merge to `<integration-branch>`
+
+### Placement
+- Decision: <core | customer | customer-shared | defer-extract>
+- Core release required: <yes — packages + versions | no>
+
+### Changes
+- <bullet summary>
+
+### Validation
+- <commands run>
+
+### Merge order (if multi-repo)
+1. <core PR / npm publish>
+2. <customer pnpm update @se-studio/...>
+3. <customer PR>
+
+### Production
+Ready for you to merge to `main` / promote Vercel. Agent will not push production.
+```
+
+---
+
+## Step 9 — Complete or park
+
+| Outcome | Manifest update |
+|---------|-----------------|
+| Merged / done | Move to `work/completed/<feature>.yaml` or delete from `work/active/` |
+| Blocked | `status: blocked`, set `blocked_on` |
+| Parked | `status: parked`, add `parked_reason` |
+
+Remove worktree when done:
+
+```bash
+git worktree remove <worktree-path>
+```
+
+---
+
+## Session opener (user control surface)
+
+User can paste:
+
+```
+Load skill: site-workflows-agent-session
+Mode: site-first
+Project: om1
+Feature: hero-redesign
+Branch: feature/om1/hero-redesign
+```
+
+Agent must load this skill, write manifest, run placement checklist, confirm branch/worktree, then proceed.
+
+---
+
+## Quick reference — project keys
+
+| key | Integration branch | Type |
+|-----|-------------------|------|
+| `se-core-product` | `dev` | core monorepo |
+| `se2026` | `develop` | customer |
+| `brightline` | `develop` | customer monorepo |
+| `om1` | `develop` | customer |
+| `pointme` | `develop` | customer |
+| `pedestal` | `develop` | customer monorepo |
+| `hsd-extended-port` | `extended-port` | customer (WIP) |
+
+Full paths and MCP keys: `projects.registry.json`.

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

@@ -11,7 +11,31 @@ 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/`; bypass or remove `minimumReleaseAge`.
+**Never:** push to `main`/`master`; bump Next to 16; bump Node to 25+; use `pnpm patch` / `patchedDependencies` / `patches/`; bypass or remove `minimumReleaseAge`; **hand-edit `package.json` dependency versions** (use `pnpm update` instead).
+
+---
+
+## Bumping packages (all repos — agents must follow)
+
+**Do not** edit `package.json` version strings by hand. Always run `pnpm update` from the repo root so `pnpm-lock.yaml` stays aligned.
+
+```bash
+# One package after a core npm release
+pnpm update @se-studio/contentful-rest-api@<version> -r
+
+# Several @se-studio packages
+pnpm update -r @se-studio/contentful-rest-api @se-studio/core-ui
+```
+
+**`pnpm-workspace.yaml` overrides:** many customer repos pin packages under `overrides` (e.g. Point.me: `@se-studio/contentful-rest-api`, `mapbox-gl`). `pnpm update` does **not** update those lines. After updating a pinned package, set the matching override to the same range or `pnpm install --frozen-lockfile` fails.
+
+**cms-edit host repos** (`cms-edit/host` in `pnpm-workspace.yaml`): Vercel install is:
+
+```bash
+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).
 
 ---
 
@@ -25,9 +49,12 @@ Update npm dependencies to **latest** in se-core-product and consumer repos that
 | `om1` | OM1 Website | `develop` |
 | `pointme` | PointMe Marketing Site | `develop` |
 | `pedestal` | Pedestal Sites | `develop` |
+| `hsd-extended-port` | HopSkipDrive Extended Port **(WIP)** | `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.
+
 ---
 
 ## Step 1 — Preflight
@@ -103,6 +130,8 @@ Align nested `packageManager` fields (e.g. `apps/*/package.json`) with the root
 
 ## Step 5 — Update dependencies
 
+Use CLI updates only — do not StrReplace version strings in `package.json`.
+
 ```bash
 pnpm update -r --latest
 ```
@@ -147,6 +176,12 @@ rg '"node"' package.json apps/*/package.json packages/*/package.json 2>/dev/null
 
 ## Step 6 — Validate (unified for all repos)
 
+If the registry project has `cms-edit/host` in `pnpm-workspace.yaml`, run the frozen hoisted install check first:
+
+```bash
+pnpm install --frozen-lockfile --config.node-linker=hoisted
+```
+
 Always run the patches check **once**, then the project validate from the registry:
 
 ```bash
@@ -205,6 +240,7 @@ This is optional follow-up — the skill workflow always runs the check regardle
 
 | Issue | Action |
 |-------|--------|
+| `ERR_PNPM_OUTDATED_LOCKFILE` on frozen/hoisted install | `package.json` and `pnpm-workspace.yaml` overrides out of sync with lockfile — re-run `pnpm update` for the package and align `overrides` |
 | `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 |

package/skills/site-workflows-new-project/SKILL.md

@@ -71,19 +71,53 @@ Write `CLAUDE.md` at the project root:
 
 ## Step 6 — Create `AGENTS.md`
 
-Write `AGENTS.md` at the project root. Fill in the user's email address (from memory if known, otherwise ask) and today's date:
+Write `AGENTS.md` at the project root. Fill in the user's email address (from memory if known, otherwise ask) and today's date.
+
+Include the **agent session workflow block** from [`packages/skills/references/agent-session/customer-agents-block.md`](../../references/agent-session/customer-agents-block.md) (branch policy, placement, parallel features, handoff).
 
 ```markdown
 # Next.js: ALWAYS read docs before coding
 
 Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
 
+# @se-studio packages: ALWAYS read docs before coding
+
+Before using any `@se-studio/*` package, read the relevant `node_modules/@se-studio/<package>/docs/llms.md`.
+
 # userEmail
 The user's email address is [USER_EMAIL].
 
 # currentDate
 Today's date is [CURRENT_DATE].
 
+## Agent session workflow
+
+**Load skill `site-workflows-agent-session` at the start of every coding session.**
+
+Default mode for this repo: **site-first**.
+
+### Branch policy
+
+- Agents may commit and push **`develop`** and **`feature/*`** only.
+- **Never** push to `main`, `master`, or production — human-only.
+- Prefer **draft PRs** to `develop` over direct pushes when `gh` is available.
+
+### Core vs customer placement
+
+Before non-trivial code, run the placement checklist (skill `site-workflows-agent-session`). If the checklist says **core**, stop — do not patch `@se-studio` behaviour in this repo.
+
+### Core release order
+
+When work depends on a new `@se-studio/*` npm release: release from `se-core-product` first, confirm npm, then `pnpm update @se-studio/<package>@<version> -r` here, then push `develop`. Never hand-edit dependency versions.
+
+### Parallel features
+
+One feature = one `feature/<scope>/<slug>` branch. Use git worktrees for parallel work on this repo. CMS: `--session <feature-slug>`. Manifest: `~/source/se/se-core-product/work/active/<feature>.yaml`.
+
+### Production handoff
+
+Agents stop at handoff — they do not merge to `main`. See skill `site-workflows-agent-session` Step 8.
+
 ## CMS editing (cms-edit)
 
 Before any Contentful content edit: