@biggora/claude-plugins 1.1.1 → 1.2.0

package/src/skills/screen-recording/references/python-fallback.md

@@ -0,0 +1,222 @@
+# Python Fallback — Screen Recording without FFmpeg
+
+Use this approach when FFmpeg is not installed. Captures screenshots in a loop using `mss` and assembles them into MP4 with OpenCV.
+
+> **Limitations**: No audio capture, no cursor capture, lower FPS than FFmpeg, larger CPU usage.
+
+## Dependencies
+
+```bash
+pip install mss opencv-python numpy
+```
+
+## Full Working Template
+
+```python
+#!/usr/bin/env python3
+"""
+Screen recorder using Python only (mss + OpenCV).
+No FFmpeg required. Cross-platform: Windows, macOS, Linux.
+
+Limitations:
+- No audio capture
+- No cursor capture
+- Lower FPS (~15-25 depending on resolution and hardware)
+"""
+
+import time, os, sys
+import numpy as np
+import cv2
+import mss
+
+def record_screen(output="recording.mp4", duration=30, fps=20,
+                  region=None, monitor=1):
+    """
+    Record the screen using mss + OpenCV.
+
+    Args:
+        output: Output file path (.mp4)
+        duration: Recording duration in seconds
+        fps: Target frames per second (actual may be lower)
+        region: Tuple (x, y, w, h) for specific region, or None for full screen
+        monitor: Monitor number (1 = primary, 2 = secondary, etc.)
+    """
+    with mss.mss() as sct:
+        # Define capture area
+        if region:
+            x, y, w, h = region
+            capture_area = {"left": x, "top": y, "width": w, "height": h}
+        else:
+            mon = sct.monitors[monitor]  # monitors[0] is "all monitors"
+            capture_area = {
+                "left": mon["left"],
+                "top": mon["top"],
+                "width": mon["width"],
+                "height": mon["height"],
+            }
+
+        width = capture_area["width"]
+        height = capture_area["height"]
+
+        # Setup video writer
+        # Try H264 first, fall back to mp4v
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        writer = cv2.VideoWriter(output, fourcc, fps, (width, height))
+
+        if not writer.isOpened():
+            raise RuntimeError(f"Failed to open VideoWriter for {output}")
+
+        print(f"Recording {width}x{height} @ {fps}fps → {output}")
+        print(f"Duration: {duration}s (Ctrl+C to stop early)")
+
+        frame_count = 0
+        frame_interval = 1.0 / fps
+        start_time = time.time()
+
+        try:
+            while True:
+                frame_start = time.time()
+                elapsed = frame_start - start_time
+
+                if elapsed >= duration:
+                    break
+
+                # Capture screenshot
+                screenshot = sct.grab(capture_area)
+                # Convert BGRA → BGR (OpenCV format)
+                frame = np.array(screenshot)[:, :, :3]
+                # mss returns BGRA, but numpy slice gives BGR which is what OpenCV expects
+
+                writer.write(frame)
+                frame_count += 1
+
+                # Frame rate control
+                frame_time = time.time() - frame_start
+                sleep_time = frame_interval - frame_time
+                if sleep_time > 0:
+                    time.sleep(sleep_time)
+
+        except KeyboardInterrupt:
+            print("\nStopped by user.")
+
+        writer.release()
+        actual_duration = time.time() - start_time
+        actual_fps = frame_count / actual_duration if actual_duration > 0 else 0
+        size = os.path.getsize(output) if os.path.exists(output) else 0
+
+        print(f"Saved: {output}")
+        print(f"  Frames: {frame_count}")
+        print(f"  Duration: {actual_duration:.1f}s")
+        print(f"  Actual FPS: {actual_fps:.1f}")
+        print(f"  Size: {size:,} bytes ({size // 1024} KB)")
+
+        return output
+
+
+def list_monitors():
+    """List available monitors and their dimensions."""
+    with mss.mss() as sct:
+        for i, mon in enumerate(sct.monitors):
+            if i == 0:
+                print(f"  [0] All monitors combined: {mon['width']}x{mon['height']}")
+            else:
+                print(f"  [{i}] Monitor {i}: {mon['width']}x{mon['height']} at ({mon['left']}, {mon['top']})")
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Record screen (Python only)")
+    parser.add_argument("output", nargs="?", default="recording.mp4")
+    parser.add_argument("--duration", "-t", type=int, default=30)
+    parser.add_argument("--fps", type=int, default=20)
+    parser.add_argument("--region", "-r", type=str, default=None,
+                        help="x,y,w,h (e.g. 100,200,800,600)")
+    parser.add_argument("--monitor", "-m", type=int, default=1,
+                        help="Monitor number (default: 1 = primary)")
+    parser.add_argument("--list-monitors", action="store_true",
+                        help="List available monitors and exit")
+    args = parser.parse_args()
+
+    if args.list_monitors:
+        list_monitors()
+        sys.exit(0)
+
+    region = tuple(map(int, args.region.split(","))) if args.region else None
+    record_screen(args.output, args.duration, args.fps, region, args.monitor)
+```
+
+## Multi-Monitor Support
+
+```python
+with mss.mss() as sct:
+    # sct.monitors[0] = virtual screen (all monitors combined)
+    # sct.monitors[1] = primary monitor
+    # sct.monitors[2] = secondary monitor, etc.
+
+    # Record specific monitor
+    mon = sct.monitors[2]  # secondary monitor
+    screenshot = sct.grab(mon)
+
+    # Record all monitors as one image
+    screenshot = sct.grab(sct.monitors[0])
+```
+
+## Performance Tips
+
+### Reduce resolution for higher FPS
+```python
+# Capture at half resolution, then resize for writing
+frame = np.array(sct.grab(capture_area))[:, :, :3]
+small = cv2.resize(frame, (width // 2, height // 2))
+writer.write(small)
+```
+
+### Use JPEG compression for intermediate frames
+```python
+# For very long recordings, write frames as JPEG to reduce memory/disk
+_, buf = cv2.imencode('.jpg', frame, [cv2.IMWRITE_JPEG_QUALITY, 85])
+# Later decode for video assembly
+```
+
+### Codec alternatives
+```python
+# mp4v — most compatible, larger files
+fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+
+# XVID — better compression (requires ffmpeg/xvid codec)
+fourcc = cv2.VideoWriter_fourcc(*"XVID")
+# Output file should be .avi for XVID
+
+# H264 — best compression (may not be available everywhere)
+fourcc = cv2.VideoWriter_fourcc(*"avc1")  # macOS
+fourcc = cv2.VideoWriter_fourcc(*"H264")  # Linux
+```
+
+## Adding Audio After Recording
+
+If you need audio, record video with this script, then merge audio separately:
+
+```python
+import subprocess
+
+def add_audio_to_video(video_path, audio_path, output_path):
+    """Merge separately-recorded audio into the video."""
+    subprocess.run([
+        "ffmpeg", "-i", video_path, "-i", audio_path,
+        "-c:v", "copy", "-c:a", "aac", "-b:a", "128k",
+        "-shortest", output_path, "-y", "-loglevel", "quiet"
+    ], check=True)
+```
+
+## Comparison: Python Fallback vs FFmpeg
+
+| Feature | Python (mss+cv2) | FFmpeg Native |
+|---------|-------------------|---------------|
+| **FPS** | 15-25 (resolution-dependent) | 30-60 |
+| **Audio** | No | Yes |
+| **Cursor** | No | Yes |
+| **CPU Usage** | Higher | Lower |
+| **Dependencies** | pip only | System FFmpeg |
+| **File Size** | Larger (mp4v codec) | Smaller (H.264) |
+| **Setup** | Easier | Requires FFmpeg install |
+| **Reliability** | Good | Excellent |

package/src/skills/tm-search/SKILL.md

@@ -16,123 +16,283 @@ description: >
 
 This skill enables an agent to search, validate, and analyze US trademarks via USPTO APIs.
 
-## API Overview
+## Important: API Access Reality
+
+The USPTO trademark search system (`tmsearch.uspto.gov`) uses **AWS WAF bot protection** on its
+Elasticsearch search backend. Direct keyword search via HTTP is **not possible** without browser
+automation. However, the **TSDR details API** (case lookup by serial number) works without
+authentication and returns JSON.
+
+For **keyword search**, use one of these approaches:
+1. **Playwright/browser automation** — drive the tmsearch.uspto.gov web UI (most reliable)
+2. **Third-party API** — RapidAPI USPTO wrapper (requires API key, simpler to use)
 
-There are **two main API approaches** — choose based on needs:
+For **case status lookup by serial number**, the built-in TSDR API works directly.
 
-| Use Case | API |
+## API Overview
+
+| Use Case | Approach |
 |---|---|
-| Keyword/name text search, availability check | **tmsearch.uspto.gov** (web backend) |
-| Status lookup by serial/registration number | **tsdrapi.uspto.gov** (official TSDR API) |
-| Batch/programmatic word validation | **tmsearch.uspto.gov** or RapidAPI wrapper |
+| Keyword/name text search | Browser automation on tmsearch.uspto.gov **or** RapidAPI |
+| Case status by serial number | TSDR Details API (no auth, JSON) |
+| Batch keyword validation | Browser automation + delays **or** RapidAPI |
+| Case documents / images | TSDR API (requires API key since Oct 2024) |
 
 ---
 
-## API 1: tmsearch.uspto.gov (New Trademark Search — No API key required)
+## API 1: TSDR Details API (No auth required — JSON)
 
-The USPTO replaced TESS in November 2023 with a new search system at `https://tmsearch.uspto.gov`.
-This is a **web application** but its backend can be called directly.
+Look up trademark case details **by serial number**. This endpoint is hosted on the tmsearch
+site and returns JSON without authentication.
 
-### Search Endpoint
+### Endpoint
 
 ```
-POST https://tmsearch.uspto.gov/search/keyword
-Content-Type: application/json
+GET https://tmsearch.uspto.gov/tsdr-api-v1-0-0/tsdr-api?serialNumber={SERIAL_NUMBER}
 ```
 
-**Request body:**
-```json
-{
-  "keyword": "APPLE",
-  "searchType": "1",
-  "statusType": "A",
-  "pluralVariants": false,
-  "start": 0,
-  "rows": 25
-}
-```
-
-**Parameters:**
-- `keyword` — the word/phrase to search (required)
-- `searchType` — `"1"` = basic keyword, `"2"` = design code, `"3"` = owner name
-- `statusType` — `"A"` = active/live only, `"D"` = dead only, `""` = all
-- `pluralVariants` — `true` to include plural variations
-- `start` — pagination offset (0-indexed)
-- `rows` — results per page (max 500)
-
-### Alternative: GET search
+Serial numbers are 8 digits (no dashes). Example:
 
-```
-GET https://tmsearch.uspto.gov/search/keyword?keyword=APPLE&statusType=A&rows=25
+```bash
+curl -s "https://tmsearch.uspto.gov/tsdr-api-v1-0-0/tsdr-api?serialNumber=78787878" \
+  -H "Accept: application/json"
 ```
 
-### Response Fields
+### Response Structure
 
 ```json
 {
-  "totalFound": 1247,
-  "trademarks": [
+  "metadata": {
+    "caseStatus": "Abandoned because the applicant failed to respond...",
+    "statusDate": "2007-09-25",
+    "owners": [
+      {
+        "ipInfo": {
+          "name": "OWNER NAME",
+          "legalEntity": "3",
+          "contactAddress": {
+            "mailingAddresses": [
+              {
+                "cityName": "City",
+                "geographicRegionName": "STATE",
+                "postalCode": "12345",
+                "countryName": "UNITED STATES OF AMERICA"
+              }
+            ]
+          },
+          "citizenship": {
+            "countryName": "UNITED STATES OF AMERICA",
+            "geographicRegionName": "STATE"
+          }
+        }
+      }
+    ],
+    "attorney": {
+      "ipInfo": { "name": "Attorney Name" }
+    },
+    "correspondent": {
+      "ipInfo": {
+        "name": "Correspondent Name",
+        "contactAddress": { "mailingAddresses": [...], "electronicAddresses": [...] }
+      }
+    },
+    "markDetails": {
+      "isStandardCharClaimed": false
+    },
+    "tm5Status": {
+      "tm5StatusDescription": "...",
+      "tm5StatusCode": "10",
+      "tm5StatusDescriptor": "DEAD/APPLICATION/Refused/Dismissed or Invalidated",
+      "tm5LiveDead": "dead"
+    },
+    "classes": [
+      { "classNumber": "009", "firstUseAnywhereDate": null, "firstUseInCommerceDate": null }
+    ],
+    "docketNumber": "..."
+  },
+  "maintenance": {},
+  "prosecutionHistory": [
     {
-      "serialNumber": "75123456",
-      "registrationNumber": "2345678",
-      "wordMark": "APPLE",
-      "status": "Live/Registered",
-      "statusCode": "A",
-      "filingDate": "1997-03-15",
-      "registrationDate": "1999-08-17",
-      "owner": "Apple Inc.",
-      "ownerAddress": "Cupertino, CALIFORNIA, UNITED STATES",
-      "internationalClassification": ["009", "042"],
-      "goodsServices": "Computers, computer software...",
-      "attorney": "...",
-      "markDrawingCode": "4"
+      "historyDate": "2026-03-06",
+      "historyDescription": "Amended Drawing",
+      "documentId": "https://tsdr.uspto.gov/documentviewer?caseId=sn78787878&docId=..."
     }
-  ]
+  ],
+  "assignments": [...],
+  "proceedings": [...],
+  "international": {}
 }
 ```
 
-> **Note:** The tmsearch.uspto.gov backend API is not officially documented. If the above endpoint
-> returns errors, fall back to scraping `https://tmsearch.uspto.gov/search/search-information` or
-> use the TSDR API below. See `references/scraping-fallback.md` for the web scraping approach.
+### Key Response Fields
 
----
+| Path | Description |
+|---|---|
+| `metadata.caseStatus` | Human-readable current status |
+| `metadata.statusDate` | Date of last status change |
+| `metadata.owners[].ipInfo.name` | Owner/applicant name |
+| `metadata.owners[].ipInfo.contactAddress` | Owner address |
+| `metadata.attorney.ipInfo.name` | Attorney of record |
+| `metadata.tm5Status.tm5LiveDead` | `"live"` or `"dead"` |
+| `metadata.tm5Status.tm5StatusDescriptor` | Structured status (e.g., `"LIVE/REGISTRATION/Registered"`) |
+| `metadata.classes[].classNumber` | Nice Classification codes |
+| `metadata.markDetails.isStandardCharClaimed` | Whether it's a standard character mark |
+| `prosecutionHistory[]` | Timeline of case events with document links |
+
+> **Note:** This API does NOT return the word mark text itself. To get the mark text, you need
+> the keyword search approach (browser automation or RapidAPI).
 
-## API 2: TSDR API (Official — requires API key for bulk use)
+---
 
-Looks up trademark **by serial number or registration number**. Returns full case status, documents.
+## API 2: TSDR Bulk API (Requires API key — XML)
 
-**Base URL:** `https://tsdrapi.uspto.gov/ts/cd/`
+The original TSDR API at `tsdrapi.uspto.gov` now **requires an API key for all requests** (changed
+October 2024). Register at https://account.uspto.gov/api-manager/.
 
-### Key Endpoints
+### Endpoints
 
 ```bash
-# Case status by serial number (HTML)
-GET https://tsdrapi.uspto.gov/ts/cd/casestatus/sn{SERIAL_NUMBER}/content.html
-
-# Case status as XML (machine-readable)
+# Case status as XML (requires API key)
 GET https://tsdrapi.uspto.gov/ts/cd/casestatus/sn{SERIAL_NUMBER}/info.xml
+  Header: USPTO-API-KEY: YOUR_KEY
+
+# Case status as HTML
+GET https://tsdrapi.uspto.gov/ts/cd/casestatus/sn{SERIAL_NUMBER}/content.html
+  Header: USPTO-API-KEY: YOUR_KEY
 
-# Case status by registration number
+# By registration number
 GET https://tsdrapi.uspto.gov/ts/cd/casestatus/rn{REG_NUMBER}/info.xml
 
-# Case documents as PDF bundle
+# Case documents PDF bundle
 GET https://tsdrapi.uspto.gov/ts/cd/casedocs/bundle.pdf?sn={SERIAL_NUMBER}
 
 # Raw trademark image
 GET https://tsdrapi.uspto.gov/ts/cd/rawImage/{SERIAL_NUMBER}
 ```
 
-### API Key (required for bulk/automated use)
+Rate limit: **60 requests/minute per API key**.
+
+---
+
+## Keyword Search via Browser Automation (Recommended)
+
+Since the tmsearch.uspto.gov search backend is protected by AWS WAF, use Playwright to drive
+the web UI and intercept API responses.
+
+**Important:** The AWS WAF bot detection is non-deterministic — headless browsers are blocked
+intermittently. Use anti-detection settings and retries. Even with these, keyword search may
+fail occasionally. The RapidAPI wrapper (below) is more reliable if you need consistent results.
+
+```python
+from playwright.sync_api import sync_playwright
+
+def search_trademark(keyword: str, max_results: int = 25) -> dict:
+    """Search USPTO trademarks by keyword using browser automation."""
+    results = {"totalFound": 0, "trademarks": []}
+
+    with sync_playwright() as p:
+        # Anti-detection settings to bypass AWS WAF
+        browser = p.chromium.launch(
+            headless=True,
+            args=["--disable-blink-features=AutomationControlled"],
+        )
+        context = browser.new_context(
+            user_agent=(
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/120.0.0.0 Safari/537.36"
+            ),
+            viewport={"width": 1920, "height": 1080},
+        )
+        page = context.new_page()
+        page.add_init_script(
+            'Object.defineProperty(navigator, "webdriver", {get: () => undefined})'
+        )
+
+        # Intercept the Elasticsearch API responses
+        def handle_response(response):
+            if "prod-stage" in response.url and response.status == 200:
+                try:
+                    data = response.json()
+                    if isinstance(data, dict) and "hits" in data:
+                        hits = data.get("hits", {})
+                        total = hits.get("total", {})
+                        results["totalFound"] = total.get("value", 0) if isinstance(total, dict) else total
+                        for hit in hits.get("hits", [])[:max_results]:
+                            results["trademarks"].append(hit.get("_source", {}))
+                except Exception:
+                    pass
+
+        page.on("response", handle_response)
+        page.goto("https://tmsearch.uspto.gov/search/search-information", timeout=30000)
+        page.wait_for_load_state("networkidle")
+        page.wait_for_timeout(2000)  # Wait for WAF challenge to resolve
+
+        # Type keyword and submit
+        search_input = page.locator('input[type="text"]').first
+        search_input.fill(keyword.upper(), timeout=10000)
+        search_input.press("Enter")
+
+        # Wait for results (longer wait needed for WAF + async results)
+        page.wait_for_timeout(6000)
+
+        browser.close()
+
+    return results
+```
+
+### Install Playwright
+
+```bash
+pip install playwright
+playwright install chromium
+```
+
+---
+
+## Keyword Search via RapidAPI (Alternative — requires API key)
+
+If browser automation is not practical, the RapidAPI unofficial USPTO wrapper provides reliable
+keyword search.
 
-- Register at: https://account.uspto.gov/api-manager/
-- Add key as header: `USPTO-API-KEY: YOUR_KEY_HERE`
-- Rate limit: **60 requests/minute per API key**
+**Sign up:** https://rapidapi.com/pentium10/api/uspto-trademark
 
 ```bash
-curl -H "USPTO-API-KEY: YOUR_KEY" \
-  "https://tsdrapi.uspto.gov/ts/cd/casestatus/sn78787878/info.xml"
+# Keyword search (active marks)
+curl "https://uspto-trademark.p.rapidapi.com/v1/trademarkSearch/APPLE/active" \
+  -H "x-rapidapi-host: uspto-trademark.p.rapidapi.com" \
+  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"
+
+# Availability check
+curl "https://uspto-trademark.p.rapidapi.com/v1/trademarkAvailable/CLOUDPEAK" \
+  -H "x-rapidapi-host: uspto-trademark.p.rapidapi.com" \
+  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"
+
+# Search by owner
+curl "https://uspto-trademark.p.rapidapi.com/v1/ownerSearch/Apple%20Inc/" \
+  -H "x-rapidapi-host: uspto-trademark.p.rapidapi.com" \
+  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"
+
+# Lookup by serial number
+curl "https://uspto-trademark.p.rapidapi.com/v1/serialSearch/78787878" \
+  -H "x-rapidapi-host: uspto-trademark.p.rapidapi.com" \
+  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY"
+
+# Batch search (POST)
+curl -X POST "https://uspto-trademark.p.rapidapi.com/v1/batchTrademarkSearch" \
+  -H "x-rapidapi-host: uspto-trademark.p.rapidapi.com" \
+  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"keywords": ["CLOUDPEAK", "SKYBRIDGE", "NEONPULSE"]}'
 ```
 
+RapidAPI endpoints:
+- `/v1/trademarkSearch/{keyword}/{status}` — keyword search (`active`, `dead`, or `all`)
+- `/v1/trademarkAvailable/{keyword}` — simple yes/no availability
+- `/v1/ownerSearch/{owner_name}/{postcode}` — search by owner
+- `/v1/serialSearch/{serial_number}` — lookup by serial number
+- `/v1/batchTrademarkSearch` — multiple keywords (POST)
+
 ---
 
 ## CLI Tool Implementation (tm-search)
@@ -142,11 +302,11 @@ When building the `tm-search` command-line tool, follow this structure:
 ### Core Commands
 
 ```bash
-tm-search keyword <word>              # Search by keyword
+tm-search keyword <word>              # Search by keyword (uses Playwright)
 tm-search keyword <word> --status=A  # Active trademarks only
 tm-search keyword <word> --status=D  # Dead trademarks only
 tm-search available <word>           # Check if word is available (not registered live)
-tm-search status <serial_number>     # Lookup by serial number
+tm-search status <serial_number>     # Lookup by serial number (uses TSDR API)
 tm-search batch <word1,word2,...>    # Check multiple words
 tm-search validate <file.txt>        # Validate words from a file (one per line)
 ```
@@ -177,58 +337,34 @@ Top matches:
 A keyword is considered **AVAILABLE** if there are zero live/active marks with exact OR confusingly
 similar text. The agent should:
 
-1. Search exact keyword with `statusType=A`
+1. Search exact keyword (via Playwright or RapidAPI)
 2. If results > 0 → **LIKELY REGISTERED** — show matches
 3. If results == 0 → **LIKELY AVAILABLE** — note this is not legal advice
 4. Always caveat: suggest professional trademark attorney review before filing
 
-```python
-def check_availability(keyword):
-    results = search_trademark(keyword, status="A")
-    if results["totalFound"] == 0:
-        return "LIKELY AVAILABLE"
-    else:
-        return f"LIKELY TAKEN ({results['totalFound']} active marks)"
-```
-
 ---
 
 ## Batch Validation
 
-For validating a list of keywords (e.g., from a CSV or text file):
-
-```python
-words = ["CloudPeak", "SkyBridge", "NeonPulse"]
-results = []
-for word in words:
-    r = search_trademark(word.upper(), status="A")
-    results.append({
-        "keyword": word,
-        "status": "AVAILABLE" if r["totalFound"] == 0 else "TAKEN",
-        "count": r["totalFound"]
-    })
-# Output as table or CSV
-```
-
-Rate-limit: Add 0.5–1s delay between requests to avoid throttling.
+For validating a list of keywords, add a 2–3 second delay between Playwright searches to avoid
+triggering rate limits. With RapidAPI, 0.5–1s delay is sufficient.
 
 ---
 
 ## Implementation Notes
 
-- The `tmsearch.uspto.gov` endpoint is a **public government site** — no auth required for search
+- The `tmsearch.uspto.gov` search backend is protected by **AWS WAF** — direct HTTP keyword search does not work
+- The TSDR Details API (`/tsdr-api-v1-0-0/tsdr-api?serialNumber=...`) works without auth and returns JSON
+- The old TSDR XML API (`tsdrapi.uspto.gov`) requires an **API key for all requests** since October 2024
 - Always **uppercase** keywords before searching (USPTO stores marks in uppercase)
-- Include `User-Agent` header to avoid bot detection: `"Mozilla/5.0 (compatible; tm-search/1.0)"`
-- For `pluralVariants=true`, USPTO auto-expands COFFEE → COFFEES, etc.
 - International Classification (Nice Classification) codes define goods/services category
 - Serial numbers are 8 digits; Registration numbers are 7 digits
 
 ## Reference Files
 
 - `references/field-guide.md` — Full field descriptions and Nice Classification codes
-- `references/scraping-fallback.md` — Web scraping approach if API is unavailable
+- `references/scraping-fallback.md` — Browser automation fallback details
 - `scripts/tm_search.py` — Ready-to-use Python implementation
-- `scripts/tm_validate.py` — Batch validation script
 
 ---
 
@@ -237,4 +373,4 @@ Rate-limit: Add 0.5–1s delay between requests to avoid throttling.
 Always include when providing availability results:
 > "This is a preliminary search only. Trademark availability is complex and depends on many
 > factors including similar marks, geographic use, and goods/services classification. Consult a
-> licensed trademark attorney before filing."
+> licensed trademark attorney before filing."