@se-studio/skills 1.2.3 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @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

package/package.json

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