@se-studio/skills 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @se-studio/skills
 
+## 1.3.0
+
+### Minor Changes
+
+- Add `screaming-frog-audit` agent skill for Screaming Frog crawl, native compare, and prioritized audit workflows.
+
+## 1.2.3
+
+### Patch Changes
+
+- Bulk version bump: patch for all packages
+
 ## 1.2.2
 
 ### Patch Changes

package/package.json

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

package/skills/contentful-cms-core/SKILL.md

@@ -479,10 +479,16 @@ cms-edit types component
 cms-edit types collection
 
 # List entries with filters
+cms-edit list --type article --sort date -n 10     # recent articles by publication date
 cms-edit list --type article --has-download       # articles with a download asset
 cms-edit list --type article --slug my-article    # article with a specific slug
 cms-edit list --type article --has-field tags      # articles where tags field is non-empty
 
+# Find draft articles, then peek/open (both support drafts via CMA)
+cms-edit sitemap --include article --status draft
+cms-edit peek --article-slug resources/blog/my-post
+# Only list --published / resolve --published are published-only
+
 # Resolve any entry or asset by ID (no open session required)
 cms-edit resolve --id 4xKj2abcDefGhijK             # entry: shows type, title, slug, status
 cms-edit resolve --id 7pQrStuvWxyzAbc              # asset: shows title, fileName, URL
@@ -702,6 +708,7 @@ cms-edit sitemap                         # All pages, sorted by slug
 cms-edit sitemap --prefix /blog          # Filter by slug prefix
 cms-edit sitemap --status draft          # Draft pages only
 cms-edit sitemap --sort updated          # Most recently updated first
+cms-edit sitemap --include article --sort date  # Articles by publication date
 cms-edit sitemap --tree                  # Tree rendering
 cms-edit sitemap --include page,article  # Include articles too
 ```

package/skills/contentful-cms-regenerate-editor-pack/SKILL.md

@@ -27,13 +27,15 @@ Run after any of these change:
 
 | Action | Automatic on git push? |
 |--------|------------------------|
-| Copy **committed** `editor-pack/` into cms-edit-host | Yes (when `cms-edit/**` changes and Vercel builds) |
+| Copy **committed** `editor-pack/` + `.mcpb` into cms-edit-host | Yes (`stage-site.mjs` on Vercel build) |
 | Run `editor-pack generate` | **No** — always manual (this skill) |
-| Rebuild `.mcpb` on Vercel | Yes (part of customer `vercel-build.sh`) |
+| Rebuild `.mcpb` on Vercel | **No** — commit locally (`pnpm cms-edit:mcpb` or `build-mcpb.sh`) when `hosted.mcpUrl` or extension metadata changes |
 | Update hosted guide/prompts from `@se-studio/contentful-cms` | Redeploy host after bumping package version |
 
 Editors do **not** reinstall `.mcpb` when only the editor pack changes.
 
+**Staging:** `stage-site.mjs` copies committed artifacts into `cms-edit/host/` before build. Requires `CMS_EDIT_ROOT` on Vercel. Single-site repos default to `cms-edit` locally; multi-site repos need `CMS_EDIT_ROOT` in `cms-edit/host/.env.local`. Run manually with `pnpm cms-edit:stage` (or site-specific variant).
+
 ## Step 1 — Locate config
 
 | Repo layout | Config path |
@@ -84,17 +86,17 @@ git commit -m "chore(cms-edit): regenerate editor pack"
 
 ## Step 6 — Deploy
 
-### SE Studio (git-connected Vercel)
+### Customer repo with `cms-edit/host/` (SE Studio, Pedestal, Headwater)
 
-Push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger `cms-edit/scripts/vercel-build.sh`, which copies the committed pack and rebuilds the host.
+Commit `editor-pack/` (and `.mcpb` if `hosted.mcpUrl` changed), then push to the branch Vercel watches (usually `develop`). Changes under `cms-edit/**` trigger a host rebuild (`stage-site.mjs` copies committed artifacts).
 
 ```bash
 git push
 ```
 
-No `pnpm cms-edit:deploy` needed unless you want a manual Vercel deploy without pushing.
+Manual deploy without pushing: `pnpm cms-edit:deploy` (single-site) or `pnpm cms-edit:deploy:<site>` (multi-site) — runs validate, stage, then `vercel deploy --prod`.
 
-### Other customers (e.g. Pedestal)
+### Customers without `cms-edit/host/` in their repo
 
 From `se-core-product`:
 
@@ -105,8 +107,6 @@ From `se-core-product`:
   --prod
 ```
 
-Or commit + push if that customer repo has its own cms-edit-host Vercel project.
-
 ## Homepage slug reminder
 
 SE Studio sites store the marketing homepage as Contentful slug **`index`** (public URL `/`). Regenerated `routing.md` documents this. Set `website.homepageSlug` in `project.json` only for exceptions (e.g. Pedestal `home`).

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

@@ -0,0 +1,104 @@
+---
+name: screaming-frog-audit
+description: "Crawl a marketing site with Screaming Frog, run native compare mode between crawls, and generate prioritized audit/compare reports via @se-studio/site-check and seo/screaming-frog.json."
+---
+
+# Screaming Frog crawl, compare, and audit
+
+Use when the user wants a Screaming Frog crawl, before/after deployment comparison, or SEO issue audit (404s, canonicals, structured data, content/metadata regressions).
+
+**Requires:** Screaming Frog SEO Spider (licensed), **database storage mode** (default with `--save-crawl`).
+
+**Config:** each app's `seo/screaming-frog.json` — no site-specific presets in core product.
+
+---
+
+## Deployment workflow (content push → code release)
+
+Typical process: crawl after CMS/content is on preview, then crawl again after code ships, and confirm no significant content/metadata regressions.
+
+### 1. Baseline after content push
+
+From the app directory:
+
+```bash
+pnpm seo:screaming-frog:baseline
+# equivalent:
+site-check-screaming-frog crawl --tag content
+```
+
+This crawls with the manifest profile, saves to SF's database, and records the database ID as baseline `content` in `docs/seo/sf-crawl-state.json`.
+
+### 2. Crawl after code release
+
+```bash
+pnpm seo:screaming-frog:crawl
+```
+
+Records the new crawl as `lastCrawl` in `sf-crawl-state.json`.
+
+### 3. Native compare (before vs after)
+
+```bash
+pnpm seo:screaming-frog:compare
+# equivalent:
+site-check-screaming-frog compare --baseline content
+```
+
+Uses Screaming Frog **`--crawl-comparison <current-db-id> <previous-db-id>`** (native Compare mode), exports Change Detection CSVs, and writes `docs/seo/<site>-screaming-frog-compare.md`.
+
+Exit code 1 when title/meta/H1/word-count regressions are detected.
+
+### 4. Optional full issue audit
+
+```bash
+pnpm seo:screaming-frog ~/spider/exports/<timestamp>
+```
+
+Prioritized P0–P3 report from a single crawl export.
+
+---
+
+## Other commands
+
+```bash
+site-check-screaming-frog profiles          # show crawl profiles from manifest
+site-check-screaming-frog list-crawls     # SF database IDs for this siteHost
+site-check-screaming-frog compare --latest   # two most recent crawls (same host)
+site-check-screaming-frog compare <current-id> <previous-id>  # explicit IDs
+```
+
+---
+
+## What native compare checks
+
+SF Change Detection exports (current vs previous on **matched URLs**):
+
+- Page titles, meta descriptions, H1
+- Word count (flags ≥50 words or ≥10% change)
+- Indexability status
+- Structured data type changes (via dedicated export tab)
+
+Does **not** replace a full audit for new 404s — run `audit` on the post-release export for issue triage.
+
+---
+
+## Prerequisites
+
+| Item | Notes |
+|------|-------|
+| SF GUI | Quit before CLI crawl/compare (shared DB lock) |
+| Vercel preview | Bypass header in `.seospiderconfig`; `PREVIEW_SITE_URL` in `.env.local` |
+| Same profile | Compare only meaningful when both crawls use the same URL/profile |
+| Database storage | `--save-crawl` stores crawls; compare needs two DB IDs |
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---------|-----|
+| 0 matched URLs in compare | Different URLs/host between crawls — use same profile |
+| No baseline | Run `crawl --tag content` first |
+| GUI lock / FATAL | Quit Screaming Frog app |
+| Wrong crawls picked | `list-crawls` then pass explicit database IDs |

package/skills/screaming-frog-audit/references/profiles.md

@@ -0,0 +1,62 @@
+# Screaming Frog site config
+
+Each project owns **`seo/screaming-frog.json`** at the app root (or pass `--config` explicitly). The core product package has no built-in site presets.
+
+## Required fields
+
+| Field | Purpose |
+|-------|---------|
+| `site` | Short site key (for logging) |
+| `siteLabel` | Display name in audit report |
+| `siteHost` | Host substring for filtering redirect samples |
+| `defaultSiteUrl` | Fallback URL when crawl overview is missing |
+| `outputMdName` | Audit markdown filename (written under `docs/seo/`) |
+| `profiles` | Named crawl targets with `configFile` paths |
+
+## Optional fields
+
+| Field | Purpose |
+|-------|---------|
+| `defaultProfile` | Profile used when `--profile` is omitted |
+| `productionAuditDoc` | Cross-link in report to live HTML audit doc |
+| `issueRuleOverrides` | Per-site P0–P3 rule tweaks (merged over base rules in `@se-studio/site-check`) |
+
+## Example manifest
+
+```json
+{
+  "site": "brightline",
+  "siteLabel": "Brightline",
+  "siteHost": "hellobrightline.com",
+  "defaultSiteUrl": "https://www.hellobrightline.com/",
+  "outputMdName": "brightline-screaming-frog-audit.md",
+  "defaultProfile": "preview",
+  "issueRuleOverrides": [
+    {
+      "match": "directives_noindex",
+      "tier": "p2",
+      "category": "indexing",
+      "note": "Expected on Vercel preview."
+    }
+  ],
+  "profiles": {
+    "production": {
+      "label": "Production",
+      "url": "https://www.hellobrightline.com/",
+      "configFile": "~/spider/bl production.seospiderconfig"
+    },
+    "preview": {
+      "label": "Vercel preview",
+      "urlEnv": "PREVIEW_SITE_URL",
+      "configFile": "~/spider/bl dev.seospiderconfig"
+    },
+    "localhost": {
+      "label": "Local dev",
+      "url": "http://localhost:3010/",
+      "configFile": "~/spider/bl localhost.seospiderconfig"
+    }
+  }
+}
+```
+
+`.seospiderconfig` files live outside the repo (typically `~/spider/`). Preview configs should embed the Vercel bypass header.