opencode-skills-collection 3.0.36 → 3.0.38

package/bundled-skills/hasdata-cli/references/search.md

@@ -0,0 +1,122 @@
+# Search references
+
+Subcommands: `google-serp`, `google-serp-light`, `google-ai-mode`, `google-news`, `google-shopping`, `bing-serp`, `google-trends`, `google-images`, `google-events`, `google-short-videos`, `google-immersive-product`.
+
+For `google-flights`, see `travel.md`.
+
+Run `hasdata <api> --help` for the live, authoritative flag set. Below are the commonly-used flags and example invocations.
+
+---
+
+## google-serp (10 credits)
+
+```bash
+hasdata google-serp --q "QUERY" [--gl COUNTRY] [--hl LANG] [--num 10] [--start 0] --raw | jq .
+```
+
+Common flags:
+- `--q TEXT` (required) — search query
+- `--gl us|gb|ca|de|fr|...` — country code; affects results
+- `--hl en|es|fr|de|...` — UI language
+- `--num 10..100` — results per page
+- `--start 0|10|20...` — pagination offset (multiples of 10)
+- `--location "Austin,Texas,United States"` — Google canonical location
+- `--device-type desktop|mobile|tablet`
+- `--tbm isch|vid|nws|shop|lcl` — search type
+- `--safe active|off`
+- `--lr lang_en --lr lang_fr` — restrict to language(s)
+- `--domain google.com|google.co.uk|...`
+- `--tbs cdr:1,cd_min:10/17/2018,cd_max:3/8/2021` — advanced search filters
+
+Useful response fields (via `jq`):
+- `.organic_results[] | {title, link, snippet}` — main results
+- `.ai_overview` — AI Overview block (when present)
+- `.answer_box`, `.knowledge_graph`, `.related_searches`, `.people_also_ask`
+- `.local_results`, `.shopping_results`, `.news_results`
+
+Example — top-10 organic for prompt grounding:
+```bash
+hasdata google-serp --q "$Q" --num 10 --raw \
+  | jq -r '.organic_results[] | "- \(.title): \(.snippet)"'
+```
+
+## google-serp-light (5 credits)
+
+Same flags as `google-serp` but cheaper and returns a single page. Use when the user wants quick results and doesn't need PAA/AI Overview/local sections.
+
+## google-ai-mode (5 credits)
+
+Returns Google's AI Mode answer for a query. Same `--q` / `--gl` / `--hl` semantics.
+
+## google-news (10 credits)
+
+```bash
+hasdata google-news --q "QUERY" [--gl us] [--hl en] --raw | jq '.news_results[]'
+```
+
+Per-article fields: `title`, `link`, `source.name`, `date`, `snippet`, `thumbnail`.
+
+## google-shopping (10 credits)
+
+```bash
+hasdata google-shopping --q "PRODUCT" [--gl us] --raw | jq '.shopping_results[]'
+```
+
+Per-result: `title`, `link`, `price`, `extracted_price`, `source`, `rating`, `reviews`, `delivery`.
+
+## bing-serp (10 credits)
+
+```bash
+hasdata bing-serp --q "QUERY" [--cc us] [--setlang en] --raw | jq '.organic_results[]'
+```
+
+Use when the user explicitly asks for Bing or wants a non-Google second opinion.
+
+## google-trends (5 credits)
+
+```bash
+hasdata google-trends --q "TERM" [--geo US] [--cat 0] [--time "today 12-m"] --raw | jq .
+```
+
+Multiple terms for comparison: `--q "term1,term2,term3"` (comma-separated, max 5).
+
+## google-images (5 credits)
+
+```bash
+hasdata google-images --q "QUERY" --raw | jq '.images_results[] | {title, original, source}'
+```
+
+## google-events (5 credits)
+
+```bash
+hasdata google-events --q "concerts in austin" [--gl us] --raw | jq '.events_results[]'
+```
+
+## google-short-videos (10 credits) / google-immersive-product (5 credits)
+
+Less common — run `--help` to see flags when needed.
+
+---
+
+## Non-obvious use cases
+
+- **Fact-check a claim before answering** — instead of relying on training data, run `google-serp --q "EXACT CLAIM"` and check whether top results corroborate or contradict.
+- **Resolve "what is the URL for X?"** — agents often hallucinate URLs. `google-serp --q "X official site" --num 3` and pick the result with the matching domain.
+- **Source-find a quote** — `google-serp --q "\"the exact quoted text here\""` (escape the inner quotes). Returns the page that originated it.
+- **Compare same query across regions** — same `--q`, different `--gl us|gb|de|fr` to see how SERP differs by geo. Useful for international SEO and "what do users in country Y see".
+- **Time-bound search** — `--tbs qdr:d` (past day), `qdr:w` (week), `qdr:m` (month), `qdr:y` (year). Combine with `google-news` for fresh-only news. Or `--tbs cdr:1,cd_min:M/D/YYYY,cd_max:M/D/YYYY` for an explicit window.
+- **Site-restricted search** — `--q "site:example.com TOPIC"` to search within one domain (better than scraping the site's own search box).
+- **"What's been written about X recently?"** — `google-news --q "X" --gl us` then `jq` over `.news_results[] | select(.date | test("hours? ago|day ago"))`.
+- **Discover competitors** — `google-serp --q "best alternatives to PRODUCT"` followed by extracting brand names from the top results' titles.
+- **Find documentation links** — `google-serp --q "LIBRARY official docs"` instead of guessing a URL pattern.
+- **Translate search intent** — `--hl de --gl de --q "the English query"` shows German-language ranking; useful for multi-locale SEO checks.
+- **Trends over time** — `google-trends --q "term1,term2"` (comma-separated, ≤5 terms) for relative interest curves. Better than guessing "is X popular now" from training data.
+- **Image-driven research** — `google-images --q "X"` to grab source URLs; pipe top results into `web-scraping` to read context.
+- **Map-distance trick** — for "things near X", use `google-maps --ll "@LAT,LNG,Zz"` not a SERP query — much higher signal for proximity intent.
+- **Fact-check pricing** — when training data has stale prices for SaaS or subscription services, search and read the pricing page rather than answering from memory.
+
+## Picking the right SERP variant
+
+- Use `google-serp-light` when only top organic results are needed (skips PAA / AI overview / local sections).
+- Use `google-serp` when you need the full SERP feature set (PAA, AI overview, knowledge graph, local pack).
+- Cache results client-side when running the same query repeatedly — the CLI does not cache.

package/bundled-skills/hasdata-cli/references/travel.md

@@ -0,0 +1,102 @@
+# Travel reference
+
+Subcommands:
+- `airbnb-listing`, `airbnb-property` (5 credits each) — short-term rentals.
+- `booking-search`, `booking-place` (10 credits each) — hotels and other lodging on Booking.com.
+- `google-flights` (15 credits) — flight prices and itineraries via Google Flights.
+
+`*-listing` / `*-search` is the filtered search; `*-property` / `*-place` is a single-property deep dive.
+
+For activities at the destination see `google-events` (in `search.md`); for ground transport scrape the operator's site with `web-scraping`.
+
+---
+
+## airbnb-listing
+
+```bash
+hasdata airbnb-listing --location "Lisbon, Portugal" \
+  --check-in 2026-06-15 --check-out 2026-06-22 \
+  --adults 2 --price-max 200 --raw
+```
+
+Run `--help` for the full filter set (room type, amenities, instant book, etc.).
+
+## airbnb-property
+
+```bash
+hasdata airbnb-property --url "https://www.airbnb.com/rooms/12345678" --raw
+```
+
+## booking-search (10 credits)
+
+```bash
+hasdata booking-search \
+  --keyword "Lisbon" \
+  --check-in-date 2026-07-10 --check-out-date 2026-07-13 \
+  --adults 2 --children 0 --rooms 1 \
+  [--price-min 50 --price-max 250] [--rating 4 --rating 5] \
+  [--review-score reviewScoreVeryGood --review-score reviewScoreSuperb] \
+  [--property-type hotels --property-type apartments] \
+  [--meals breakfastIncluded] [--facilities freeParking --facilities pool] \
+  [--sort priceLowestFirst|ratingHighToLow|topReviewed|...] \
+  [--page 2] [--currency USD] [--language en-us] \
+  --raw | jq '.results[]'
+```
+
+Required (no defaults work in production, even though `--help` shows them): `--keyword`, `--check-in-date`, `--check-out-date`, `--adults`, `--children`, `--rooms`. Pass `--children 0` explicitly when none.
+
+When `--children > 0`, **also pass `--children-ages-json '[5,7]'`** with one age per child (0–17). Booking rejects the request otherwise.
+
+Bracketed price filters (`--price-min` / `--price-max`) require `>= 10` / `>= 20` respectively; one of the two is required when filtering on price.
+
+Top-level response: `results`, `searchInformation`, `pagination`, `requestMetadata`. Per-result keys (verified live): `hotelId`, `roomId`, `title`, `url`, `location`, `rating`, `reviews`, `price`, `room`, `beds`, `bedTypes`, `policies`, `photo`.
+
+```bash
+# Cheap-first filtered search
+hasdata booking-search --keyword "Paris" \
+  --check-in-date 2026-08-01 --check-out-date 2026-08-04 \
+  --adults 2 --children 0 --rooms 1 \
+  --review-score reviewScoreVeryGood \
+  --sort priceLowestFirst --raw \
+  | jq -c '.results[] | {title, price: .price.total, rating, url}'
+```
+
+## booking-place (10 credits)
+
+```bash
+hasdata booking-place \
+  --url "https://www.booking.com/hotel/fr/le-bristol-paris.html" \
+  --check-in-date 2026-07-10 --check-out-date 2026-07-13 \
+  --adults 2 --children 0 --rooms 1 \
+  [--currency USD] [--language en-us] \
+  --raw | jq .
+```
+
+Required: `--url` (must be on `booking.com` / `www.booking.com`), stay dates, `--adults`, `--children`, `--rooms`.
+
+Response: `overview`, `bookingDetails`, `rooms[]`, `facilities`, `houseRules`, `ratings`, `reviews`, `restaurants`, `breadcrumbs`, `questionsAndAnswers`. `overview` carries `id`, `title`, `address`, `description`, `propertyType`, `photos`, `highlights`, `mostPopularFacilities`. Each `rooms[i]` has `roomId`, `name`, `bedTypes`, `beds`, `facilities`, `otherFacilities`, `variants[]` (pricing/availability per package).
+
+## google-flights (15 credits)
+
+```bash
+hasdata google-flights \
+  --departure-id "JFK" --arrival-id "LAX" \
+  --outbound-date 2026-06-15 --return-date 2026-06-22 \
+  --currency USD --raw | jq .
+```
+
+Round-trip vs. one-way controlled by presence/absence of `--return-date`. Run `--help` for the full flag set (cabin class, max stops, preferred airlines, etc.).
+
+---
+
+## Non-obvious use cases
+
+- **Hotel-vs-rental arbitrage** — same dates and party size via `booking-search` and `airbnb-listing`; compare nightly cost percentile-for-percentile. The cheaper platform isn't always the same one across cities.
+- **Conference-room pricing audit** — `booking-search --keyword "$CITY" --check-in-date $START --check-out-date $END --sort priceHighestFirst` during a known conference window vs an idle week; the delta is the conference premium.
+- **Family-friendly filter** — `--children-ages-json '[5,9]' --children 2 --rooms 1 --travel-group family` and Booking returns only properties that accept the party size with appropriate beds.
+- **Loyalty-program portfolio** — `booking-search --keyword "$CITY" --raw | jq '.results[] | select(.title | test("Marriott|Hilton|Hyatt"))'` filters to chains you collect points with.
+- **Airbnb price-arbitrage check** — same dates, same area, two `airbnb-listing` calls with different `--adults` counts to surface listings that don't scale per-person price. Sometimes the difference is the deal.
+- **STR-vs-LTR feasibility** — pair `airbnb-listing` for nightly rates with `zillow-listing --type forSale` (see `real-estate.md`) for purchase price in the same area; compute gross yield client-side.
+- **Flights without a travel API** — `google-flights` with `--departure-id`, `--arrival-id`, dates, and `--currency` for ad-hoc fare checks against a vendor like Skyscanner.
+- **Multi-leg cost planning** — chain `google-flights` calls for each leg and sum `.best_flights[].price`; cheaper than the round-trip price-bot SaaS for one-off itineraries.
+- **Trip-cost preview** — combine `google-flights` (transport) + `booking-search` / `airbnb-listing` (lodging) + `google-events` (activities, see `search.md`) into one cost estimate before pitching a destination.

package/bundled-skills/hasdata-cli/references/web-scraping.md

@@ -0,0 +1,181 @@
+# web-scraping reference
+
+Subcommand: `web-scraping` (10 credits/call). Single endpoint for arbitrary URL scraping with JS rendering, proxies, AI extraction, screenshots, markdown conversion.
+
+> **`web-scraping` is the last resort, not the default.** Before reaching for it, ask: would `google-serp` (or `google-news` / `google-shopping` / `google-maps`) already have the field I need? Google's `.knowledge_graph`, `.organic_results[].snippet`, `.local_results[]` carry pre-extracted public facts without direct page access. Only invoke `web-scraping` when:
+>
+> - the user gave you a specific URL to read, OR
+> - SERP came up short for a specific field, OR
+> - the target page renders content that doesn't show up in any SERP snippet.
+>
+> Use it only for public pages or content the user is authorized to access, and respect site terms, robots/access controls, privacy law, and rate limits.
+>
+> See `references/enrichment.md` for the SERP-first patterns.
+
+```bash
+hasdata web-scraping --url "URL" [flags] --raw | jq .
+```
+
+## Required
+
+- `--url URL` — target page
+
+## Output formats
+
+- `--output-format html|text|markdown|json` (repeatable)
+  - One format → that format directly (e.g. `--output-format markdown` returns markdown text under `.markdown`)
+  - Multiple → JSON response with one key per format
+  - `--output-format json` combined with others → wraps everything in JSON
+
+```bash
+# LLM-friendly markdown for prompt context
+hasdata web-scraping --url "$URL" --output-format markdown --raw | jq -r .markdown
+```
+
+## Proxy & rendering
+
+- `--proxy-type datacenter|residential` (default datacenter)
+- `--proxy-country US|UK|DE|IE|FR|IT|SE|BR|CA|JP|SG|IN|ID` (default US)
+- `--js-rendering` / `--no-js-rendering` (default on) — full headless browser
+- `--block-ads` / `--no-block-ads` (default on)
+- `--block-resources` / `--no-block-resources` (default on) — blocks images/CSS for speed
+- `--screenshot` / `--no-screenshot` (default on; the result includes a screenshot URL)
+- `--remove-base64-images` — strip inline base64 images from response
+- `--extract-emails` / `--no-extract-emails` (default on)
+- `--extract-links` (default off)
+
+## Wait controls
+
+- `--wait MS` — fixed wait after page load
+- `--wait-for "CSS_SELECTOR"` — wait until selector appears
+
+## Custom JS scenario (complex array — JSON only)
+
+```bash
+hasdata web-scraping --url "$URL" \
+  --js-scenario-json '[
+    {"wait": 2000},
+    {"click": ".load-more"},
+    {"waitFor": ".item"},
+    {"scrollY": 1000},
+    {"fill": ["input#q", "espresso"]}
+  ]' --raw
+```
+
+Supported actions: `evaluate`, `click`, `wait`, `waitFor`, `waitForAndClick`, `scrollX`, `scrollY`, `fill`. Executed sequentially.
+
+Accepts raw JSON, `@file.json`, or `-` (stdin).
+
+## Headers (kvSlice + JSON escape)
+
+```bash
+# Repeatable kv form (splits on first `=`)
+hasdata web-scraping --url "$URL" \
+  --headers "User-Agent=hasdata-cli" \
+  --headers "Accept-Language=en-US,en;q=0.9" \
+  --headers "Cookie=session=abc=def" \
+  --raw
+
+# JSON base + kv overrides
+hasdata web-scraping --url "$URL" \
+  --headers-json '{"User-Agent":"base","X-Common":"shared"}' \
+  --headers "User-Agent=override" \
+  --raw
+```
+
+## CSS-selector data extraction (kvSlice or JSON)
+
+```bash
+# Lightweight kv form: --extract-rules KEY=SELECTOR
+hasdata web-scraping --url "https://quotes.toscrape.com" \
+  --extract-rules "quote=.quote .text" \
+  --extract-rules "author=.quote .author" \
+  --raw | jq .
+
+# JSON form for complex selectors / attributes
+hasdata web-scraping --url "$URL" \
+  --extract-rules-json '{"title":"h1","links":"a @href","price":".price-now"}' \
+  --raw
+```
+
+`@href`, `@src`, etc. extract attributes. Without `@`, extracts text content.
+
+## AI extraction (LLM-driven)
+
+```bash
+hasdata web-scraping --url "$URL" \
+  --ai-extract-rules-json '{
+    "headline": {"type": "string", "description": "the main story headline"},
+    "comments_count": {"type": "number"},
+    "is_paid_content": {"type": "boolean"},
+    "tags": {"type": "list", "description": "topic tags"},
+    "author": {"type": "item", "output": {
+      "name": {"type": "string"},
+      "verified": {"type": "boolean"}
+    }}
+  }' --raw | jq .
+```
+
+Supported types: `string`, `number`, `boolean`, `list`, `item` (nested object — defines its shape under `output`).
+
+## Tag filtering
+
+- `--include-only-tags "main,article"` (comma-joined CSS selectors) — keep only matching elements
+- `--exclude-tags script --exclude-tags style` (repeatable) — remove elements
+
+```bash
+hasdata web-scraping --url "$URL" \
+  --output-format markdown \
+  --include-only-tags "article,main" \
+  --exclude-tags script --exclude-tags style --exclude-tags nav \
+  --raw | jq -r .markdown
+```
+
+## URL blocklist
+
+```bash
+--block-urls-json '["**.googletagmanager.com/**","**.doubleclick.net/**"]'
+```
+
+Glob patterns block specific subresource URLs from loading.
+
+## Saving binary output
+
+The `web-scraping` response is JSON, but if `--output-format` is set to a single non-JSON format, the wrapped result is still JSON. Use `jq -r .markdown > file.md` to extract text. For screenshots specifically, the response contains a screenshot URL — fetch it separately with `curl`.
+
+## Non-obvious use cases
+
+- **Page-to-prompt grounding** — `--output-format markdown` produces clean LLM-ready text from any URL. Strip nav/ads with `--exclude-tags script --exclude-tags style --exclude-tags nav`. Beats fetch + regex.
+- **JavaScript-rendered SPAs that `curl` can't read** — default `--js-rendering` uses a real browser, so React/Vue/Angular pages return their hydrated DOM, not the empty shell.
+- **Geo/availability testing where allowed** — `--proxy-type residential` can model residential network availability; use only for authorized tests where the target's terms and access controls permit it.
+- **Geo-targeted content** — `--proxy-country DE` to see what users in Germany see (different prices, currencies, A/B variants, or geo-blocked content).
+- **Quick "is this page real" check** — `--screenshot` (default on) returns a screenshot URL in the response; verify visually without manually opening the URL.
+- **Universal price extractor** — `--ai-extract-rules-json '{"price":{"type":"number"},"currency":{"type":"string"},"in_stock":{"type":"boolean"}}'` works on arbitrary retailer pages without writing a CSS selector. Cheaper than maintaining per-site selectors when the user only needs occasional spot-checks.
+- **Authenticated content with user authority** — `--headers Cookie=session=...` injects auth cookies if the user has them. Use only with explicit permission and authority to access that account/content; never use cookies to bypass someone else's access controls.
+- **Convert paginated lists to a clean record set** — combine `--js-scenario-json` (click "Load more" 5×) with `--ai-extract-rules-json` (pull the list shape). Lets you scrape paginated SPAs with one CLI call instead of N.
+- **Headless screenshot of a layout** — set `--js-rendering`, `--no-block-resources` (so CSS loads), and capture the screenshot URL from the response. Useful for "render this URL and show me what it looks like".
+- **Markdown for RAG ingestion** — pipe `.markdown` from many URLs into a JSONL corpus; embed and store. The CLI handles JS, ads, images so you don't need a custom pipeline.
+- **Fallback for any other API** — when no purpose-built API exists for a vertical (e.g. niche directories, government pages, less-popular real-estate sites), `web-scraping` is the catch-all.
+- **Detect content changes** — schedule `web-scraping --url X --output-format markdown` and diff the output across runs to flag pricing-page or terms-of-service changes.
+- **Read PDFs / non-HTML resources** — `--output-format text` works on text-extractable PDFs accessible via URL (the underlying renderer handles them).
+- **AI extraction for forms or tables** — pages with structured data in HTML tables are easy: `--ai-extract-rules-json '{"rows":{"type":"list","output":{"name":{"type":"string"},"value":{"type":"number"}}}}'`. The model fills in nested rows.
+
+## Common patterns
+
+```bash
+# Full-page markdown for RAG
+hasdata web-scraping --url "$URL" \
+  --output-format markdown --no-screenshot --no-block-resources \
+  --raw | jq -r .markdown >> corpus.md
+
+# JS-heavy SPA: wait + scroll
+hasdata web-scraping --url "$URL" \
+  --js-scenario-json '[{"wait":2000},{"scrollY":2000},{"wait":1500}]' \
+  --wait-for ".item" \
+  --output-format html --raw | jq -r .html
+
+# Extract structured data from an arbitrary page
+hasdata web-scraping --url "$URL" \
+  --ai-extract-rules-json '{"price":{"type":"number"},"in_stock":{"type":"boolean"}}' \
+  --raw | jq .
+```

package/bundled-skills/hasdata-cli/references/youtube.md

@@ -0,0 +1,145 @@
+# YouTube reference
+
+Subcommands: `youtube-search-api`, `youtube-video-api`, `youtube-channel-api`, `youtube-transcript-api`. 10 credits each.
+
+`*-search-api` is keyword-driven; the others target a specific video, channel, or transcript. Most workflows chain search → video → transcript.
+
+---
+
+## youtube-search-api
+
+```bash
+hasdata youtube-search-api --q "QUERY" [--sort-by relevance|date|views|rating|popularity] \
+  [--length under4|between420|plus20] [--date hour|today|week|month|year] \
+  [--video-type video|shorts|channel|playlist|movie] \
+  [--gl us] [--hl en] [--device-type desktop|mobile] \
+  [--pagination-token TOKEN] --raw | jq .
+```
+
+Common flags:
+- `--q TEXT` (required)
+- `--sort-by relevance|date|views|rating|popularity`
+- `--date hour|today|week|month|year` — upload-recency window
+- `--length under4|between420|plus20` — duration bucket (`<4m`, `4–20m`, `>20m`)
+- `--video-type video|shorts|channel|playlist|movie`
+- `--filters hd,k4,hdr,subtitles,cc,d3,d360,vr180,live,bought,location` — feature flags ANDed
+- `--gl`, `--hl` — country / language
+- `--pagination-token` — copy from previous response's `pagination.nextPageToken`
+- `--sp` — raw YouTube `sp=` filter token (overrides `sort-by` / `date` / `video-type` / `length` / `filters`)
+
+Top-level response keys: `videoResults`, `shortsResults`, `channelResults`, `playlistResults`, `adsResults`, `sponsoredResults`, `searchInformation`, `pagination`.
+
+Per-video result: `videoId`, `title`, `link`, `channel`, `description`, `length`, `views`, `viewsOriginal`, `publishedDate`, `thumbnail`, `positionOnPage`.
+
+```bash
+# Latest videos for a topic
+hasdata youtube-search-api --q "$Q" --sort-by date --date week --raw \
+  | jq -c '.videoResults[] | {title, channel: .channel.name, views, publishedDate, link}'
+```
+
+## youtube-video-api
+
+```bash
+hasdata youtube-video-api --v-param VIDEO_ID [--gl us] [--hl en] --raw | jq .
+```
+
+- `--v-param` (required) — 11-char video ID (the `v=` part of the watch URL)
+- `--device-type desktop|mobile`
+- `--gl`, `--hl`
+
+Top-level fields: `videoId`, `title`, `description`, `channel`, `views`, `extractedViews`, `likes`, `extractedLikes`, `lengthSeconds`, `publishedDate`, `keywords[]`, `captions`, `socialLinks`, `music`, `category`, `thumbnail`, `isFamilySafe`, `isUnlisted`, `relatedVideos[]`, `relatedShorts[]`, `endScreenVideos[]`.
+
+```bash
+# Quick stats
+hasdata youtube-video-api --v-param "$VID" --raw \
+  | jq '{title, views: .extractedViews, likes: .extractedLikes, length: .lengthSeconds, published: .publishedDate, channel: .channel.name}'
+```
+
+## youtube-channel-api
+
+```bash
+hasdata youtube-channel-api --channel-id "@HANDLE_OR_UCID" \
+  [--tab featured|videos|shorts|streams|playlists|posts|community|podcasts|releases|about|store] \
+  [--gl us] [--hl en] [--pagination-token TOKEN] --raw | jq .
+```
+
+- `--channel-id` (required) — `@handle`, `UC…` canonical ID, or legacy `/c/<custom>` / `/user/<name>` URL slug
+- `--tab` — which tab to scrape; default `featured` (Home page)
+- `--pagination-token` — for tabs that paginate (`videos`, `shorts`, etc.)
+
+Top-level response: `channelInfo`, `featuredVideo`, `sections[]`.
+
+`channelInfo` carries: `name`, `handle`, `channelId`, `channelUrl`, `avatar`, `banner`, `description`, `subscribers`, `extractedSubscribers`, `videosCount`, `extractedVideosCount`, `keywords[]`, `availableTabs[]`, `verified`, `websiteUrl`, `rssUrl`, `isFamilySafe`.
+
+```bash
+# All uploads (paginated)
+hasdata youtube-channel-api --channel-id "@MrBeast" --tab videos --raw \
+  | jq -c '.sections[].items[]? | {title, videoId, views, publishedDate}'
+```
+
+## youtube-transcript-api
+
+```bash
+hasdata youtube-transcript-api --v-param VIDEO_ID [--language-code en] [--type asr] --raw | jq .
+```
+
+- `--v-param` (required) — 11-char video ID
+- `--language-code` — BCP-47 / YouTube code (`en`, `de`, `en-US`, `pt-BR`); must match a track the video actually has
+- `--type asr` — fetch the auto-generated speech-recognition track (omit for human-authored)
+
+Response: `transcript[]` and `availableTranscripts[]`.
+
+Each `transcript[]` entry: `startMs`, `endMs`, `snippet`, `startTimeText`. Join `snippet`s to reconstruct the full text.
+
+```bash
+# Flatten to plain text
+hasdata youtube-transcript-api --v-param "$VID" --raw \
+  | jq -r '.transcript[].snippet' | tr '\n' ' '
+```
+
+---
+
+## Non-obvious use cases
+
+- **"What is this video actually about?"** — `youtube-transcript-api --v-param X --raw | jq -r '.transcript[].snippet'` → feed to an LLM for a real summary, not a thumbnail / title guess.
+- **Cite YouTube content in a brief** — transcript + timestamps lets you quote with `(02:14)` accuracy. `--type asr` fills the gap when the creator never uploaded captions.
+- **Channel growth audit** — `youtube-channel-api --channel-id @X --tab videos` paginated; `jq '.sections[].items[] | {publishedDate, views: .extractedViews}'` gives a velocity-over-time table.
+- **Trend discovery** — `youtube-search-api --q "TOPIC" --sort-by views --date month` returns the highest-viewed videos in the last month — a leading indicator for cultural trends well before they hit Google News.
+- **Competitor content map** — `youtube-channel-api --channel-id @competitor --tab videos --raw | jq -r '.sections[].items[].title'` enumerates every published title, useful for content-gap analysis.
+- **Brand-safety scan** — `youtube-search-api --q "BRAND" --sort-by date --date week --raw | jq '.videoResults[] | select(.title | test("BRAND"; "i"))'` catches new mentions before they go viral.
+- **Influencer due diligence** — combine `youtube-channel-api` for subscriber/video counts with `youtube-video-api` on their top videos (engagement rate ≈ `likes / views`).
+- **"Find the moment they said X"** — `youtube-transcript-api` then `jq -r '.transcript[] | select(.snippet | test("X"; "i")) | "\(.startTimeText): \(.snippet)"'` returns timestamps of every mention.
+- **Music-licensing lookup** — `youtube-video-api --v-param X --raw | jq .music` returns identified tracks (artist, title) when YouTube's Content ID matched.
+- **Translate / re-localize a video** — pull the English transcript with `youtube-transcript-api`, translate via LLM, regenerate subtitles. Cheaper than re-transcribing audio.
+- **Build a podcast / RSS feed for a channel** — `youtube-channel-api --raw | jq -r .channelInfo.rssUrl` returns the official RSS URL; subscribe in any podcast app.
+- **Detect deleted videos** — `youtube-video-api --v-param X` returns an error for removed videos; useful for catching takedowns in archival pipelines.
+- **Bulk research → transcript chain** — `youtube-search-api --q "$Q" --raw | jq -r '.videoResults[].videoId' | xargs -I{} hasdata youtube-transcript-api --v-param {} --raw` builds a research corpus from a topic search.
+- **Shorts-only / long-form-only feeds** — `--video-type shorts` vs `--length plus20` to bias toward one format.
+- **Live-stream discovery** — `--filters live` returns only currently live broadcasts; pair with `--sort-by date` for fresh streams.
+
+## Pipelines
+
+```bash
+# Search → top 5 video transcripts as a corpus
+hasdata youtube-search-api --q "$Q" --sort-by views --raw \
+  | jq -r '.videoResults[:5][].videoId' \
+  | while read -r vid; do
+      echo "=== $vid ==="
+      hasdata youtube-transcript-api --v-param "$vid" --raw \
+        | jq -r '.transcript[].snippet'
+    done > corpus.txt
+
+# Channel → CSV of all videos
+hasdata youtube-channel-api --channel-id "@$HANDLE" --tab videos --raw \
+  | jq -r '.sections[].items[]? | [.videoId, .title, (.extractedViews // 0), .publishedDate] | @csv' \
+  > channel_videos.csv
+```
+
+## Gotchas
+
+- **`--v-param` is exactly 11 chars** — not the full watch URL. Strip the `v=` value or use `jq -r '.videoResults[0].videoId'` from a prior search.
+- **`--language-code` must exist on the video.** Pass one of the codes listed in `availableTranscripts[]`, or omit for the default track.
+- **`--type asr` is needed when no human-authored captions exist.** Without it the API returns the default human track and errors if there isn't one.
+- **`@handle` is preferred over `UC…`** — easier to read, same result. Legacy `/c/` and `/user/` slugs also resolve.
+- **`pagination.nextPageToken` is opaque** — pass it back via `--pagination-token` verbatim; don't try to decode.
+- **`views` vs `extractedViews`** — `views` is the formatted string (`"1.2M views"`), `extractedViews` is the integer. Use the integer for math.