@se-studio/skills 1.3.1 → 1.3.4

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @se-studio/skills
 
+## 1.3.4
+
+### Patch Changes
+
+- **cms-seo-audit:** Document sitemap+unindexed crawl, all-page `.md` requirement, and expected listing-hub noise.
+
+## 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

package/package.json

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

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

@@ -0,0 +1,178 @@
+---
+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-audit` (production HTML audit). Screaming Frog: **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 **sitemap.xml + sitemap-unindexed.xml**, checks each URL for:
+
+- Title, meta description, H1, thin content
+- Canonical, noindex, JSON-LD validity and schema types
+- Markdown export: every sitemap page URL must return 200 for its `.md` mirror (`/download/` and static assets excluded)
+- `markdown-index.txt` cross-check (supplementary — URLs in sitemap but not in the index)
+
+High `markdown_missing` on category/listing hubs is expected until those routes ship `.md` exports.
+
+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-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/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 |