@se-studio/skills 1.3.0 → 1.3.3

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @se-studio/skills
 
+## 1.3.3
+
+### Patch Changes
+
+- Upstream CMS SEO tooling from pedestal-sites: JSON-LD `@context` fix, new `@se-studio/cms-seo` package, production HTML audit in site-check, and `cms-seo-audit` agent skill.
+
+## 1.3.2
+
+### Patch Changes
+
+- Add `cms-seo-audit` skill documenting the full CMS SEO workflow (audit CSV, apply, bulk publish, production HTML audit). Cross-link from `screaming-frog-audit` and `contentful-cms-schema-org`.
+
+## 1.3.1
+
+### Patch Changes
+
+- Move CMS guidelines prompt pack from `skills/` to `references/` so skills-npm no longer reports `file_error` for `contentful-cms-cms-guidelines`. Update pipeline doc links in CMS guideline skills.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -21,6 +21,15 @@ npx skills add @se-studio/skills
 
 Auto-sync on `pnpm install` (see [`packages/project-build/README.md`](../project-build/README.md) for the full `package.json` snippet). Use `pnpm skills:sync` manually to add or refresh third-party skill packs.
 
+## Package layout
+
+| Path | Purpose |
+|------|---------|
+| `skills/<name>/SKILL.md` | Agent skills — the only directories scanned by `skills-npm` and the skills CLI |
+| `references/<name>/` | Support docs, prompt packs, and pipeline references (no `SKILL.md`) |
+
+Do **not** place non-skill material under `skills/` — directories there without `SKILL.md` cause `file_error` warnings in consumer repos on `pnpm install`.
+
 ## Authoring skills
 
 Canonical sources live in `packages/skills/skills/<skill-dir>/SKILL.md`. Do **not** edit `.agents/skills/` by hand.
@@ -56,7 +65,7 @@ Claude Code uses a naive frontmatter parser; violations cause descriptions to si
 
 1. Edit `packages/skills/skills/<skill-dir>/SKILL.md`
 2. Validate: `pnpm skills:validate`
-3. Sync: `pnpm skills:sync`
+3. Sync: `pnpm skills:sync` (copies `skills/` → `.agents/skills/` and `references/` → `.agents/references/`)
 4. Add a changeset if publishing `@se-studio/skills`
 
 ### cms-edit bundled skills (`@se-studio/contentful-cms`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/skills",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "SE Studio agent skills for marketing site development with Contentful CMS",
   "repository": {
     "type": "git",
@@ -10,6 +10,7 @@
   "license": "MIT",
   "files": [
     "skills",
+    "references",
     "*.md"
   ],
   "keywords": [

package/{skills → references}/contentful-cms-cms-guidelines/README.md

@@ -18,7 +18,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    pnpm --filter <appName> generate-showcase
    ```
    This writes `src/generated/showcase-examples.json`.
-3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](../se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
+3. **Curate showcase mocks** — run the [curate-showcase-mocks skill](../../skills/se-marketing-sites-curate-showcase-mocks/SKILL.md) to select the best examples into `showcase-mocks.json`. This makes the showcase (and screenshots) show realistic content.
 4. **Generate field list** — parse TypeScript types to produce structured field metadata:
    ```bash
    # From the app directory:
@@ -27,7 +27,7 @@ Guidelines are short markdown fragments — one per CMS type — that describe h
    # Or from repo root:
    pnpm --filter <appName> exec cms-generate-field-list --app-dir .
    ```
-5. **Generate guidelines** — run the [Generate CMS guidelines skill](../contentful-cms-generate-cms-guidelines/SKILL.md).
+5. **Generate guidelines** — run the [Generate CMS guidelines skill](../../skills/contentful-cms-generate-cms-guidelines/SKILL.md).
 
 Steps 1–3 only need to be repeated when content or component code changes significantly. Step 4 only needs to be repeated when TypeScript types change. Step 5 can be re-run at any time.
 
@@ -35,7 +35,7 @@ Steps 1–3 only need to be repeated when content or component code changes sign
 
 ## How to run guideline generation
 
-Use the Cursor skill at [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
+Use the Cursor skill at [`../../skills/contentful-cms-generate-cms-guidelines/SKILL.md`](../../skills/contentful-cms-generate-cms-guidelines/SKILL.md). It supports three modes:
 
 | Mode | When to use |
 |---|---|

package/skills/cms-seo-audit/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: cms-seo-audit
+description: "Run the full marketing-site CMS SEO workflow: audit CSV from Contentful, apply schema/meta fixes, bulk publish, revalidate, and production HTML audit via @se-studio/cms-seo and @se-studio/site-check."
+---
+
+# CMS SEO audit, apply, publish, and production verification
+
+Use when improving SEO across a Contentful-backed SE marketing site: meta descriptions, schema.org linking, featured images, bulk publish after CMS edits, and live production HTML checks.
+
+**Packages:** `@se-studio/cms-seo` (CMS audit/apply/publish), `@se-studio/site-check` (production HTML audit, Screaming Frog — see **screaming-frog-audit** skill).
+
+---
+
+## Prerequisites
+
+| Item | Notes |
+|------|-------|
+| `.env.local` | `CONTENTFUL_SPACE_ID`, `CONTENTFUL_MANAGEMENT_TOKEN`, `CONTENTFUL_ENVIRONMENT_NAME` (usually `master`) |
+| Site config | Per-app `scripts/seo-audit.ts` with `SiteSeoConfig` (descriptions, keywords, schema IDs, path bases) |
+| Vercel | `VERCEL_PROTECTION_BYPASS_TOKEN` or `VERCEL_AUTOMATION_BYPASS_SECRET` for preview/production fetches |
+| Revalidate | After publish, trigger site revalidation (Vercel deploy hook or `revalidate` API) before production audit |
+
+---
+
+## Phase 1: Generate audit CSV (dry run)
+
+From the app directory (`apps/pedestal-website` or `apps/headwater-website`):
+
+```bash
+pnpm cms:seo-audit
+```
+
+Writes `docs/seo/<site>-seo-schema-audit.csv` with:
+
+- Meta description length and recommended copy
+- Current vs recommended schema links
+- Review status (`Approved` / `Revise` / `Skip`) and flags
+
+Review the CSV. Approve rows you want applied (or adjust `SiteSeoConfig` and re-run).
+
+Optional flags:
+
+```bash
+pnpm cms:seo-audit --sample-articles   # hub pages + 5 articles per type only
+pnpm cms:featured-images               # featured-image backfill report only
+```
+
+---
+
+## Phase 2: Apply CMS fixes
+
+```bash
+pnpm cms:seo-audit:apply
+# or featured images only:
+pnpm cms:featured-images:apply
+```
+
+**What apply does:**
+
+- Updates approved meta descriptions on pages, articles, tags, persons, indexes
+- Links canonical schema entries (Organization + WebSite on templates; WebPage on pages; CollectionPage on tags/indexes; ProfilePage on persons)
+- Creates or updates schema markup entries when templates need Org/WebSite/CollectionPage markup
+- Backfills `featuredImage` from hero visuals or site logo when `--featured-images` is set
+
+Always dry-run first. CMS changes are space-wide (master environment).
+
+---
+
+## Phase 3: Bulk publish (phased)
+
+After apply, entries are drafts until published. Use the bulk publish script (per-app `scripts/bulk-action-publish.ts` or site-common wrapper) in dependency order:
+
+```bash
+pnpm cms:bulk-publish assets
+pnpm cms:bulk-publish leaf
+pnpm cms:bulk-publish composable
+pnpm cms:bulk-publish chrome
+pnpm cms:bulk-publish taxonomy
+pnpm cms:bulk-publish article
+pnpm cms:bulk-publish page
+```
+
+Phases match Contentful link dependencies (assets → leaf types → components → chrome → taxonomy → articles → pages). Retry failed phases after fixing blocking entries.
+
+---
+
+## Phase 4: Revalidate preview / production
+
+Trigger revalidation so Next.js serves fresh CMS content:
+
+- Vercel production deploy, or
+- Site revalidate API / deploy hook
+
+Smoke-test with header nav: Pedestal `/about/`, Headwater `/`.
+
+---
+
+## Phase 5: Production HTML audit
+
+```bash
+pnpm seo:audit:production
+```
+
+Uses `@se-studio/site-check/production-audit` (`runProductionSeoAudit`). Crawls production sitemap, checks each URL for:
+
+- Title, meta description, H1, thin content
+- Canonical, noindex, JSON-LD validity and schema types
+- Markdown export parity (`index.md` / `*.md` vs HTML)
+
+Outputs:
+
+- `docs/seo/<site>-production-audit.csv`
+- `docs/seo/<site>-production-audit.md` (with Rich Results spot-checks)
+
+Exit code 1 when errors remain.
+
+---
+
+## Phase 6: Screaming Frog (optional, code-release gate)
+
+After content is on preview and again after code ships:
+
+```bash
+pnpm seo:screaming-frog:baseline    # tag: content
+pnpm seo:screaming-frog:crawl       # after code release
+pnpm seo:screaming-frog:compare
+```
+
+See **screaming-frog-audit** skill for full crawl/compare workflow.
+
+---
+
+## SiteSeoConfig checklist
+
+When adding a new site or major SEO pass, configure in `scripts/seo-audit.ts`:
+
+| Field | Purpose |
+|-------|---------|
+| `siteKey` | Identifier for logging and logo slug fallback |
+| `enableSearchAction` | `true` when site has `/search` (adds SearchAction to WebSite schema) |
+| `pageDescriptions` / `pageKeywords` | Hub and static pages by slug |
+| `indexDescriptions` / `indexKeywords` | Article type and custom type index pages |
+| `schemaIds` | Reuse existing Organization, WebSite, WebPage, CollectionPage, ProfilePage entries |
+| `articlesBase`, `tagsBase`, `peopleBase` | URL path prefixes for audit rows |
+
+Import primitives from `@se-studio/cms-seo`:
+
+```ts
+import {
+  createCmaClient,
+  parseSeoAuditArgv,
+  runSeoAudit,
+  runFeaturedImageBackfill,
+  type SiteSeoConfig,
+} from '@se-studio/cms-seo';
+```
+
+Production audit:
+
+```ts
+import {
+  runProductionSeoAudit,
+  writeProductionSeoAuditOutputs,
+  buildRichResultsSpotChecks,
+  getProductionAuditExitCode,
+} from '@se-studio/site-check/production-audit';
+```
+
+---
+
+## Related skills
+
+- **contentful-cms-schema-org** — create Mustache JSON-LD templates (manual/cms-edit path)
+- **contentful-cms-seo-descriptions** — per-page description writing via cms-edit
+- **screaming-frog-audit** — crawl/compare regression checks after code release

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

@@ -197,9 +197,9 @@ IMPORTANT: Screenshots have already been captured. Skip Phase A entirely.
 Go straight to Phase B.
 
 Files to read before starting:
-- ../contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
-- ../contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
-- ../contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
+- ../../references/contentful-cms-cms-guidelines/generation-prompt.md  (Phase B instructions)
+- ../../references/contentful-cms-cms-guidelines/colour-hint-prompt.md  (Phase C instructions)
+- ../../references/contentful-cms-cms-guidelines/validation-prompt.md   (Phase D instructions)
 - <APP_DIR>/src/project/components/<TypeName>.tsx  (component source)
 - <APP_DIR>/generated/cms-discovery/field-list.json
 - <APP_DIR>/src/generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json

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

@@ -112,7 +112,7 @@ Example of a completed `## Fields & Schema` section:
 ### Step 3 — Generate component guidelines
 
 For each component in discovery order, run the full per-component pipeline defined in
-[`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md).
+[`generate-component-guidelines.md`](../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md).
 
 To find unfinished components:
 1. Fetch `<discoveryUrl>` and collect all `components[].name` values.
@@ -128,12 +128,12 @@ Run a Cursor subagent with this prompt, substituting `<COMPONENT_TYPE>` and `<AP
 Run the full guideline generation pipeline for <COMPONENT_TYPE>.
 Target app: <APP_DIR> (all paths relative to repo root / that directory).
 
-Read these pipeline docs first (sibling directory contentful-cms-cms-guidelines/):
-- ../contentful-cms-cms-guidelines/generate-component-guidelines.md  (overall pipeline)
-- ../contentful-cms-cms-guidelines/variant-loop.md                   (Phase A: variant loop)
-- ../contentful-cms-cms-guidelines/generation-prompt.md              (Phase B: generation)
-- ../contentful-cms-cms-guidelines/colour-hint-prompt.md             (Phase C: colour hint)
-- ../contentful-cms-cms-guidelines/validation-prompt.md              (Phase D: validation)
+Read these pipeline docs first (references/contentful-cms-cms-guidelines/):
+- ../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md  (overall pipeline)
+- ../../references/contentful-cms-cms-guidelines/variant-loop.md                   (Phase A: variant loop)
+- ../../references/contentful-cms-cms-guidelines/generation-prompt.md              (Phase B: generation)
+- ../../references/contentful-cms-cms-guidelines/colour-hint-prompt.md             (Phase C: colour hint)
+- ../../references/contentful-cms-cms-guidelines/validation-prompt.md              (Phase D: validation)
 
 === Phase A: Variant loop ===
 Follow variant-loop.md.
@@ -282,7 +282,7 @@ These links:
 
 ## Pipeline reference
 
-All per-component pipeline docs live in the sibling directory [`contentful-cms-cms-guidelines/`](../contentful-cms-cms-guidelines/):
+All per-component pipeline docs live in [`references/contentful-cms-cms-guidelines/`](../../references/contentful-cms-cms-guidelines/):
 
 | File | Purpose |
 |---|---|

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

@@ -72,4 +72,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.
+See the **core** skill for the full cms-edit workflow. See the **seo-descriptions** skill for meta description generation. For bulk audit/apply across all entries, schema linking, publish phases, and production verification, see **cms-seo-audit**.

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

@@ -338,4 +338,4 @@ Follow [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-r
 | Full-site bulk generation (Step 4 of `fresh`: Phases 0–5) | [`../contentful-cms-generate-all-guidelines/SKILL.md`](../contentful-cms-generate-all-guidelines/SKILL.md) |
 | Single-type regeneration (after code change) | [`../contentful-cms-generate-cms-guidelines/SKILL.md`](../contentful-cms-generate-cms-guidelines/SKILL.md) (mode: single) |
 | Regenerate hosted editor pack | [`../contentful-cms-regenerate-editor-pack/SKILL.md`](../contentful-cms-regenerate-editor-pack/SKILL.md) |
-| Per-component pipeline detail | [`generate-component-guidelines.md`](../contentful-cms-cms-guidelines/generate-component-guidelines.md) |
+| Per-component pipeline detail | [`generate-component-guidelines.md`](../../references/contentful-cms-cms-guidelines/generate-component-guidelines.md) |

package/skills/screaming-frog-audit/SKILL.md

@@ -94,6 +94,12 @@ Does **not** replace a full audit for new 404s — run `audit` on the post-relea
 
 ---
 
+## CMS SEO workflow
+
+For Contentful meta/schema fixes before a crawl baseline, see **cms-seo-audit** (audit CSV → apply → bulk publish → `pnpm seo:audit:production`).
+
+---
+
 ## Troubleshooting
 
 | Problem | Fix |