@flitzrrr/agent-skills 1.0.2 → 1.1.0

package/skills/product-description-seo/scripts/analyze_catalog.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Analyze a JSON product catalog for thin or missing descriptions.
+
+Usage:
+    python analyze_catalog.py <catalog.json> [--category <name>] [--min-words 200]
+
+Shows per-category stats, identifies the thinnest descriptions,
+and exports batch-ready JSON when filtering by category.
+"""
+
+import json
+import sys
+import argparse
+from collections import defaultdict
+
+# Default field names (override via config)
+DESC_FIELD = "beschreibung"
+CAT_FIELD = "kategorieName"
+CAT_FIELD_ALT = "kategorie"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+STATUS_FIELD = "status"
+STATUS_ACTIVE = "aktiv"
+
+
+def count_words(text: str) -> int:
+    if not text or not text.strip():
+        return 0
+    return len(text.split())
+
+
+def analyze(catalog_path: str, category_filter: str | None = None, min_words: int = 200):
+    with open(catalog_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    products = data.get("products", [])
+    products = [p for p in products if p.get(STATUS_FIELD, STATUS_ACTIVE) == STATUS_ACTIVE]
+
+    if category_filter:
+        cf = category_filter.lower()
+        products = [p for p in products
+                    if cf in p.get(CAT_FIELD_ALT, "").lower()
+                    or cf in p.get(CAT_FIELD, "").lower()
+                    or p.get(CAT_FIELD_ALT, "").lower() == cf
+                    or p.get(CAT_FIELD, "").lower() == cf]
+
+    if not products:
+        print("No matching products found.")
+        all_cats = sorted(set(
+            p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "?"))
+            for p in data.get("products", [])
+        ))
+        if all_cats:
+            print("Available categories:")
+            for c in all_cats:
+                print(f"  - {c}")
+        return
+
+    categories = defaultdict(list)
+    for p in products:
+        cat = p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "Unknown"))
+        wc = count_words(p.get(DESC_FIELD, ""))
+        categories[cat].append({
+            SKU_FIELD: p.get(SKU_FIELD, ""),
+            NAME_FIELD: p.get(NAME_FIELD, ""),
+            "word_count": wc,
+            DESC_FIELD: p.get(DESC_FIELD, ""),
+        })
+
+    total = len(products)
+    below_threshold = sum(1 for p in products if count_words(p.get(DESC_FIELD, "")) < min_words)
+
+    print(f"{'=' * 70}")
+    print(f"CATALOG DESCRIPTION ANALYSIS")
+    print(f"{'=' * 70}")
+    print(f"Active products:       {total}")
+    below_pct = below_threshold * 100 // total if total > 0 else 0
+    above_pct = (total - below_threshold) * 100 // total if total > 0 else 0
+    print(f"Below {min_words} words:       {below_threshold} ({below_pct}%)")
+    print(f"Above {min_words} words:       {total - below_threshold} ({above_pct}%)")
+    print()
+
+    print(f"{'Category':<45} {'Count':>5} {'Avg Words':>9} {'< {}'.format(min_words):>7}")
+    print(f"{'-' * 45} {'-' * 5} {'-' * 9} {'-' * 7}")
+
+    sorted_cats = sorted(categories.items(),
+                         key=lambda x: sum(p["word_count"] for p in x[1]) / len(x[1]))
+
+    for cat_name, prods in sorted_cats:
+        avg_wc = sum(p["word_count"] for p in prods) / len(prods)
+        below = sum(1 for p in prods if p["word_count"] < min_words)
+        print(f"{cat_name:<45} {len(prods):>5} {avg_wc:>9.1f} {below:>7}")
+
+    # Thinnest descriptions
+    print(f"\n{'=' * 70}")
+    print(f"THINNEST DESCRIPTIONS (Top 20)")
+    print(f"{'=' * 70}")
+
+    all_products = []
+    for cat_name, prods in categories.items():
+        for p in prods:
+            p["_category"] = cat_name
+            all_products.append(p)
+
+    all_products.sort(key=lambda x: x["word_count"])
+
+    for i, p in enumerate(all_products[:20]):
+        print(f"\n{i + 1}. {p[NAME_FIELD]} (SKU {p[SKU_FIELD]}) — {p['_category']}")
+        print(f"   Words: {p['word_count']}")
+        desc = p[DESC_FIELD]
+        desc_preview = desc[:120] + "..." if len(desc) > 120 else (desc or "(empty)")
+        print(f'   Text: "{desc_preview}"')
+
+    # JSON export when filtering by category
+    if category_filter:
+        print(f"\n{'=' * 70}")
+        print(f"BATCH-READY JSON (Category: {category_filter})")
+        print(f"{'=' * 70}")
+        export = [{SKU_FIELD: p[SKU_FIELD], NAME_FIELD: p[NAME_FIELD],
+                    DESC_FIELD: p[DESC_FIELD], "word_count": p["word_count"]}
+                  for p in all_products]
+        print(json.dumps(export, ensure_ascii=False, indent=2))
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Analyze catalog descriptions")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("--category", "-c", help="Filter by category name (fuzzy match)")
+    parser.add_argument("--min-words", "-m", type=int, default=200,
+                        help="Minimum word count threshold (default: 200)")
+    args = parser.parse_args()
+    analyze(args.catalog_path, args.category, args.min_words)
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/check_quality.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Quality-check product descriptions against SEO requirements.
+
+Usage:
+    python check_quality.py <updates.json> [--strict] [--min-words 200] [--max-words 350]
+
+Checks each description against 8 criteria:
+1. Word count within range
+2. 4-paragraph structure
+3. Focus keyword in first sentence
+4. No banned superlatives
+5. Cross-sell reference present
+6. Formal address (no informal pronouns)
+7. Meta-description-ready opening
+8. Plain text only (no HTML/Markdown)
+"""
+
+import json
+import sys
+import re
+import argparse
+
+DEFAULT_BANNED_WORDS = [
+    # English
+    "best-in-class", "unparalleled", "revolutionary", "sensational",
+    "unmatched", "world-leading", "game-changing",
+    # German
+    "erstklassig", "herausragend", "unschlagbar", "einzigartig",
+    "revolutionaer", "sensationell", "unvergleichlich",
+    "hoechstem niveau",
+]
+
+# Indicators that a cross-sell reference is present
+CROSS_SELL_INDICATORS = [
+    "combination with", "kombination mit", "in combination",
+    "pairs well", "complement", "together with", "zusammen mit",
+    "ergaenzend", "empfehlen wir", "passend dazu",
+]
+
+# Informal pronouns that indicate wrong tone (German du-form)
+INFORMAL_PRONOUNS = [
+    r'\bdu\b', r'\bdein\b', r'\bdeine\b', r'\bdeinem\b',
+    r'\bdeinen\b', r'\bdeiner\b', r'\bdir\b', r'\bdich\b',
+]
+
+
+def check_description(product: dict, min_words: int = 200, max_words: int = 350,
+                       strict: bool = False) -> dict:
+    sku = product.get("sku", "?")
+    name = product.get("name", "?")
+    text = product.get("beschreibung", product.get("description", ""))
+
+    results = {"sku": sku, "name": name, "checks": [], "passed": 0, "failed": 0, "warnings": 0}
+
+    # 1. Word count
+    words = len(text.split())
+    if min_words <= words <= max_words:
+        results["checks"].append(("PASS", f"Word count: {words} (target: {min_words}-{max_words})"))
+        results["passed"] += 1
+    elif words > max_words:
+        results["checks"].append(("WARN", f"Word count: {words} -- above {max_words}, consider trimming"))
+        results["warnings"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Word count: {words} -- below {min_words} minimum"))
+        results["failed"] += 1
+
+    # 2. Paragraph structure
+    paragraphs = [p.strip() for p in text.split("\n\n") if p.strip()]
+    if len(paragraphs) == 4:
+        results["checks"].append(("PASS", f"4-paragraph structure: {len(paragraphs)} paragraphs"))
+        results["passed"] += 1
+    elif len(paragraphs) >= 3:
+        results["checks"].append(("WARN", f"Paragraph structure: {len(paragraphs)} paragraphs (target: 4)"))
+        results["warnings"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Paragraph structure: only {len(paragraphs)} paragraphs (target: 4)"))
+        results["failed"] += 1
+
+    # 3. Focus keyword in first sentence
+    first_sentence = text.split(".")[0].lower() if text else ""
+    name_parts = name.lower().split()
+    main_word = max(name_parts, key=len) if name_parts else ""
+    if main_word and main_word in first_sentence:
+        results["checks"].append(("PASS", f"Focus keyword in first sentence: '{main_word}' found"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Focus keyword missing in first sentence (expected: '{main_word}')"))
+        results["failed"] += 1
+
+    # 4. Banned superlatives
+    text_lower = text.lower()
+    found_banned = [w for w in DEFAULT_BANNED_WORDS if w in text_lower]
+    if not found_banned:
+        results["checks"].append(("PASS", "Tone: no banned superlatives"))
+        results["passed"] += 1
+    else:
+        level = "FAIL" if strict else "WARN"
+        results["checks"].append((level, f"Banned superlatives found: {', '.join(found_banned)}"))
+        if strict:
+            results["failed"] += 1
+        else:
+            results["warnings"] += 1
+
+    # 5. Cross-sell reference (warning only — not all products have natural cross-sells)
+    has_cross_sell = any(ind in text_lower for ind in CROSS_SELL_INDICATORS)
+    if has_cross_sell:
+        results["checks"].append(("PASS", "Cross-sell reference present"))
+        results["passed"] += 1
+    else:
+        level = "FAIL" if strict else "WARN"
+        results["checks"].append((level, "No cross-sell reference found"))
+        if strict:
+            results["failed"] += 1
+        else:
+            results["warnings"] += 1
+
+    # 6. Formal address
+    informal_found = []
+    for pattern in INFORMAL_PRONOUNS:
+        matches = re.findall(pattern, text_lower)
+        informal_found.extend(matches)
+    if not informal_found:
+        results["checks"].append(("PASS", "Formal address maintained"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("FAIL", f"Informal pronouns found: {', '.join(set(informal_found))}"))
+        results["failed"] += 1
+
+    # 7. Meta description
+    first_155 = text[:155]
+    if len(first_155) >= 100 and "." in first_155:
+        results["checks"].append(("PASS", f"Meta description: {len(first_155)} chars, contains sentence end"))
+        results["passed"] += 1
+    else:
+        results["checks"].append(("WARN", "Meta description: first 155 chars may need adjustment"))
+        results["warnings"] += 1
+
+    # 8. No HTML/Markdown
+    if re.search(r'<[^>]+>|#{1,6}\s|\*\*|__|\[.*\]\(.*\)', text):
+        results["checks"].append(("FAIL", "HTML or Markdown detected -- plain text only"))
+        results["failed"] += 1
+    else:
+        results["checks"].append(("PASS", "Plain text format (no HTML/Markdown)"))
+        results["passed"] += 1
+
+    return results
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Quality-check product descriptions")
+    parser.add_argument("updates_path", help="Path to updates JSON file")
+    parser.add_argument("--strict", action="store_true", help="Treat warnings as failures")
+    parser.add_argument("--min-words", type=int, default=200, help="Minimum word count (default: 200)")
+    parser.add_argument("--max-words", type=int, default=350, help="Maximum word count (default: 350)")
+    args = parser.parse_args()
+
+    with open(args.updates_path, "r", encoding="utf-8") as f:
+        updates = json.load(f)
+
+    print(f"{'=' * 70}")
+    print(f"QUALITY CHECK -- {len(updates)} descriptions")
+    print(f"{'=' * 70}")
+
+    total_pass = 0
+    total_fail = 0
+    total_warn = 0
+    failed_products = []
+
+    for product in updates:
+        result = check_description(product, args.min_words, args.max_words, args.strict)
+        total_pass += result["passed"]
+        total_fail += result["failed"]
+        total_warn += result["warnings"]
+
+        status = "OK" if result["failed"] == 0 else "FAIL"
+        print(f"\n[{status}] SKU {result['sku']}: {result['name']}"
+              f" ({result['passed']}P/{result['failed']}F/{result['warnings']}W)")
+
+        for check_type, msg in result["checks"]:
+            icon = {"PASS": "  [+]", "FAIL": "  [-]", "WARN": "  [!]"}[check_type]
+            print(f"  {icon} {msg}")
+
+        if result["failed"] > 0:
+            failed_products.append(f"SKU {result['sku']}: {result['name']}")
+
+    total_checks = total_pass + total_fail + total_warn
+    print(f"\n{'=' * 70}")
+    print(f"SUMMARY")
+    print(f"{'=' * 70}")
+    print(f"Products:  {len(updates)}")
+    print(f"Checks:    {total_checks} ({total_pass} passed, {total_fail} failed, {total_warn} warnings)")
+    if total_checks > 0:
+        print(f"Pass rate: {total_pass * 100 // total_checks}%")
+
+    if failed_products:
+        print(f"\nNeeds rework:")
+        for fp in failed_products:
+            print(f"  -> {fp}")
+
+    sys.exit(1 if total_fail > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/extract_category.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Extract products of a category as JSON for batch prompting.
+
+Usage:
+    python extract_category.py <catalog.json> <category-name> [--limit 8]
+
+Supports fuzzy category matching and pagination.
+"""
+
+import json
+import sys
+import argparse
+
+DESC_FIELD = "beschreibung"
+CAT_FIELD = "kategorieName"
+CAT_FIELD_ALT = "kategorie"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+STATUS_FIELD = "status"
+STATUS_ACTIVE = "aktiv"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract category products for batch prompting")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("category", help="Category name (fuzzy match)")
+    parser.add_argument("--limit", "-l", type=int, default=8,
+                        help="Max products per batch (default: 8)")
+    parser.add_argument("--offset", "-o", type=int, default=0,
+                        help="Skip first N products for pagination")
+    parser.add_argument("--thin-first", "-t", action="store_true",
+                        help="Sort thinnest descriptions first")
+    args = parser.parse_args()
+
+    with open(args.catalog_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    search = args.category.lower()
+    products = [
+        p for p in data.get("products", [])
+        if p.get(STATUS_FIELD, STATUS_ACTIVE) == STATUS_ACTIVE
+        and (search in p.get(CAT_FIELD_ALT, "").lower()
+             or search in p.get(CAT_FIELD, "").lower()
+             or p.get(CAT_FIELD_ALT, "").lower() == search
+             or p.get(CAT_FIELD, "").lower() == search)
+    ]
+
+    if not products:
+        all_cats = sorted(set(
+            p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "?"))
+            for p in data.get("products", [])
+        ))
+        print(f"No active products found for '{args.category}'.", file=sys.stderr)
+        print("Available categories:", file=sys.stderr)
+        for c in all_cats:
+            print(f"  - {c}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.thin_first:
+        products.sort(key=lambda p: len(p.get(DESC_FIELD, "").split()))
+
+    batch = products[args.offset:args.offset + args.limit]
+
+    output = []
+    for p in batch:
+        entry = {
+            SKU_FIELD: p.get(SKU_FIELD, ""),
+            NAME_FIELD: p.get(NAME_FIELD, ""),
+            DESC_FIELD: p.get(DESC_FIELD, ""),
+        }
+        # Include optional fields if present
+        for field in ["variante", "preis", "preisAufAnfrage", "einheit"]:
+            if field in p:
+                entry[field] = p[field]
+        output.append(entry)
+
+    total = len(products)
+    shown = len(batch)
+    remaining = total - args.offset - shown
+
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+    print(f"\n// Category: {args.category} | Shown: {shown}/{total}"
+          f" | Offset: {args.offset} | Remaining: {max(0, remaining)}",
+          file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/track_progress.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Track progress of a product description update campaign.
+
+Usage:
+    python track_progress.py <catalog.json> [--config product-seo-config.json] [--min-words 200]
+
+Shows overall progress, per-priority breakdown, and a next-action queue.
+Priorities are loaded from config; without config all categories are equal.
+"""
+
+import json
+import sys
+import argparse
+from collections import defaultdict
+
+DESC_FIELD = "beschreibung"
+CAT_FIELD = "kategorieName"
+CAT_FIELD_ALT = "kategorie"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+STATUS_FIELD = "status"
+STATUS_ACTIVE = "aktiv"
+
+
+def load_priorities(config_path: str | None) -> dict[str, int]:
+    """Load priority map from config. Returns {category_name: priority_level}."""
+    if not config_path:
+        return {}
+    try:
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+        prio_map = {}
+        for level, cats in config.get("priorities", {}).items():
+            for cat in cats:
+                prio_map[cat] = int(level)
+        return prio_map
+    except (FileNotFoundError, json.JSONDecodeError):
+        return {}
+
+
+def get_priority(cat_name: str, prio_map: dict[str, int]) -> int:
+    if not prio_map:
+        return 1  # No config = all equal priority
+    return prio_map.get(cat_name, 3)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Track description update progress")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("--config", help="Path to product-seo-config.json")
+    parser.add_argument("--min-words", "-m", type=int, default=200,
+                        help="Word count threshold (default: 200)")
+    args = parser.parse_args()
+
+    with open(args.catalog_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    prio_map = load_priorities(args.config)
+    products = [p for p in data.get("products", [])
+                if p.get(STATUS_FIELD, STATUS_ACTIVE) == STATUS_ACTIVE]
+
+    categories = defaultdict(lambda: {"total": 0, "done": 0, "todo": 0, "products_todo": []})
+
+    for p in products:
+        cat = p.get(CAT_FIELD, p.get(CAT_FIELD_ALT, "Unknown"))
+        wc = len(p.get(DESC_FIELD, "").split())
+        categories[cat]["total"] += 1
+        if wc >= args.min_words:
+            categories[cat]["done"] += 1
+        else:
+            categories[cat]["todo"] += 1
+            categories[cat]["products_todo"].append({
+                SKU_FIELD: p.get(SKU_FIELD, ""),
+                NAME_FIELD: p.get(NAME_FIELD, ""),
+                "words": wc,
+            })
+
+    total_products = len(products)
+    total_done = sum(c["done"] for c in categories.values())
+    total_todo = total_products - total_done
+    pct = total_done * 100 // total_products if total_products > 0 else 0
+
+    bar_len = 40
+    filled = bar_len * total_done // total_products if total_products > 0 else 0
+    bar = "#" * filled + "-" * (bar_len - filled)
+
+    print(f"{'=' * 70}")
+    print(f"PRODUCT DESCRIPTION PROGRESS")
+    print(f"{'=' * 70}")
+    print(f"\n  [{bar}] {pct}%")
+    print(f"  {total_done}/{total_products} products with >={args.min_words} words")
+    print(f"  {total_todo} remaining")
+    print(f"\n  Estimated effort: ~{total_todo // 6 + 1} batch runs at 5-8 products each")
+
+    # Determine which priority levels exist
+    prio_levels = sorted(set(get_priority(name, prio_map) for name in categories))
+
+    for prio in prio_levels:
+        prio_cats = [(name, stats) for name, stats in categories.items()
+                     if get_priority(name, prio_map) == prio]
+        if not prio_cats:
+            continue
+
+        prio_total = sum(s["total"] for _, s in prio_cats)
+        prio_done = sum(s["done"] for _, s in prio_cats)
+        prio_pct = prio_done * 100 // prio_total if prio_total > 0 else 0
+
+        label = f"PRIORITY {prio}" if prio_map else "ALL CATEGORIES"
+        print(f"\n{'-' * 70}")
+        print(f"{label} -- {prio_done}/{prio_total} done ({prio_pct}%)")
+        print(f"{'-' * 70}")
+        print(f"{'Category':<45} {'Done':>10} {'Open':>7}")
+
+        for name, stats in sorted(prio_cats, key=lambda x: x[1]["todo"], reverse=True):
+            done_str = f"{stats['done']}/{stats['total']}"
+            check = " done" if stats["todo"] == 0 else ""
+            print(f"  {name:<43} {done_str:>10} {stats['todo']:>5}  {check}")
+
+    # Next action queue
+    print(f"\n{'=' * 70}")
+    print(f"NEXT ACTIONS")
+    print(f"{'=' * 70}")
+
+    shown = 0
+    for name, stats in sorted(categories.items(),
+                               key=lambda x: (get_priority(x[0], prio_map), -x[1]["todo"])):
+        if stats["todo"] == 0:
+            continue
+        prio = get_priority(name, prio_map)
+        label = f"Prio {prio}" if prio_map else ""
+        print(f"\n  -> {name} ({label + ', ' if label else ''}{stats['todo']} open):")
+        for p in sorted(stats["products_todo"], key=lambda x: x["words"])[:5]:
+            print(f"     SKU {p[SKU_FIELD]}: {p[NAME_FIELD]} ({p['words']} words)")
+        shown += 1
+        if shown >= 5:
+            break
+
+
+if __name__ == "__main__":
+    main()

package/skills/product-description-seo/scripts/update_catalog.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Write updated product descriptions back to a catalog JSON file.
+
+Usage:
+    python update_catalog.py <catalog.json> <updates.json>
+
+updates.json format:
+[
+  {"sku": "401", "beschreibung": "New description text..."},
+  {"sku": "402", "beschreibung": "Another description..."}
+]
+
+Creates an automatic backup before writing.
+"""
+
+import json
+import sys
+import argparse
+import shutil
+from datetime import datetime
+
+DESC_FIELD = "beschreibung"
+SKU_FIELD = "sku"
+NAME_FIELD = "name"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Write updated descriptions back to catalog JSON")
+    parser.add_argument("catalog_path", help="Path to catalog JSON file")
+    parser.add_argument("updates_path", help="Path to updates JSON file")
+    args = parser.parse_args()
+
+    catalog_path = args.catalog_path
+    updates_path = args.updates_path
+
+    with open(catalog_path, "r", encoding="utf-8") as f:
+        catalog = json.load(f)
+
+    with open(updates_path, "r", encoding="utf-8") as f:
+        updates = json.load(f)
+
+    # Support both "beschreibung" and "description" field names in updates
+    update_map = {}
+    for u in updates:
+        desc = u.get(DESC_FIELD, u.get("description", ""))
+        update_map[u[SKU_FIELD]] = desc
+
+    # Create backup
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = f"{catalog_path}.backup_{timestamp}"
+    shutil.copy2(catalog_path, backup_path)
+    print(f"Backup created: {backup_path}")
+
+    updated = 0
+    not_found = []
+
+    for product in catalog.get("products", []):
+        sku = product.get(SKU_FIELD, "")
+        if sku in update_map:
+            old_wc = len(product.get(DESC_FIELD, "").split())
+            product[DESC_FIELD] = update_map[sku]
+            new_wc = len(update_map[sku].split())
+            print(f"  [+] SKU {sku}: {product.get(NAME_FIELD, '?')} ({old_wc} -> {new_wc} words)")
+            updated += 1
+            del update_map[sku]
+
+    for sku in update_map:
+        not_found.append(sku)
+        print(f"  [-] SKU {sku}: Not found in catalog")
+
+    with open(catalog_path, "w", encoding="utf-8") as f:
+        json.dump(catalog, f, ensure_ascii=False, indent="\t")
+
+    print(f"\n{updated} descriptions updated.")
+    if not_found:
+        print(f"{len(not_found)} SKUs not found: {', '.join(not_found)}")
+
+
+if __name__ == "__main__":
+    main()