opencode-skills-collection 3.0.37 → 3.0.38

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

@@ -0,0 +1,106 @@
+# E-commerce reference
+
+Subcommands: `amazon-search`, `amazon-product`, `amazon-seller`, `amazon-seller-products`, `shopify-products`, `shopify-collections`. 5 credits each.
+
+---
+
+## amazon-search
+
+```bash
+hasdata amazon-search --q "wireless earbuds" [--domain amazon.com] --raw | jq '.results[]'
+```
+
+- `--q TEXT` (required)
+- `--domain amazon.com|amazon.co.uk|amazon.de|amazon.in|amazon.co.jp|amazon.fr|amazon.it|amazon.es|amazon.com.br|amazon.com.mx|amazon.ca|amazon.com.au`
+- `--page N` — pagination
+- `--sort featured|price-asc-rank|price-desc-rank|review-rank|date-desc-rank`
+- `--node ID` — restrict to category node
+- `--customer-reviews` — only items with reviews
+
+Per-result fields: `asin`, `title`, `price`, `link`, `image`, `rating`, `reviews_count`, `prime`.
+
+## amazon-product
+
+```bash
+hasdata amazon-product --asin B08N5WRWNW [--domain amazon.com] --raw | jq .
+```
+
+- `--asin ASIN` (required)
+- `--domain` as above
+- `--include-reviews` — include first page of reviews
+- `--include-html` — return raw HTML alongside parsed data
+
+Returns: title, price, availability, features, descriptions, variants, images, ratings, top reviews, A+ content.
+
+## amazon-seller
+
+```bash
+hasdata amazon-seller --seller-id A1234567890ABC [--domain amazon.com] --raw
+```
+
+Seller profile: name, ratings, review count, returns policy, shipping policy, "About" content.
+
+## amazon-seller-products
+
+```bash
+hasdata amazon-seller-products --seller-id A1234567890ABC [--domain amazon.com] [--page 1] --raw
+```
+
+List of products from a specific seller — useful for competitor analysis or storefront crawling.
+
+---
+
+## shopify-products
+
+```bash
+hasdata shopify-products --url "https://store.example.com" [--page 1] --raw | jq '.products[]'
+```
+
+Works on any Shopify store (it queries the public `/products.json`-style endpoint). Returns title, vendor, product_type, variants[] (with prices, SKUs, stock), images, tags, handle.
+
+## shopify-collections
+
+```bash
+hasdata shopify-collections --url "https://store.example.com" --raw | jq '.collections[]'
+```
+
+For drilling into a specific collection, append `/collections/SLUG` to the URL or use the collection handle returned here.
+
+---
+
+## Non-obvious use cases
+
+- **Cross-marketplace price arbitrage** — same `--asin` across `--domain amazon.com|amazon.co.uk|amazon.de` shows currency-normalized regional differences; useful for grey-market resellers and buyers shipping internationally.
+- **"Is this product still available?"** — `amazon-product --asin X --raw | jq '.availability'`. Avoids hallucinating an answer based on stale training data.
+- **Variant matrix dump** — `amazon-product --asin X --raw | jq '.variants[] | {asin, color, size, price}'` returns the full color/size/etc. lattice with current prices.
+- **Counterfeit-listing detection** — `amazon-search --q "BRAND PRODUCT" --raw` then check `.results[].seller_name` for non-authorized sellers; pivot to `amazon-seller` to inspect their other listings.
+- **Storefront catalog** — `amazon-seller-products --seller-id X --page 1..N` paginates a seller's full catalog; useful for competitor analysis or due diligence on a vendor.
+- **"What were the bestsellers in category X?"** — `amazon-search --q "CATEGORY KEYWORD" --sort featured` returns Amazon's own ranking (`--sort review-rank` for review-weighted).
+- **Lead enrichment for a Shopify store** — `shopify-products --url store.example.com --raw` exposes vendor names, tags, product types, SKUs — useful for competitor product-line audits.
+- **Stock check** — `shopify-products` returns each variant's `available` boolean; can power "notify me when X is back" without scraping the cart UI.
+- **Price-drop monitoring** — schedule `amazon-product --asin X` daily; persist `.price` to a file; alert when delta > N%.
+- **A/B-test detection** — same `--asin` from two different `--proxy-country` settings (via web-scraping fallback if amazon-product doesn't support it) sometimes shows different price/title due to A/B tests.
+- **Gift-card / coupon discovery** — `google-shopping --q "PRODUCT"` often surfaces resellers offering rebates Amazon doesn't show.
+- **Product-image extraction for a moodboard** — `amazon-product --asin X --raw | jq -r '.images[]'` returns CDN URLs you can download separately.
+- **Compare reviews summary** — `amazon-product --asin X --include-reviews --raw | jq '.reviews[] | {rating, title, body}'` gives a quick sentiment sample without scraping the review page.
+- **Build a Shopify product feed for ads** — `shopify-products --url X --raw | jq -c '.products[] | {id, title, price: .variants[0].price, url: ("https://" + $store + "/products/" + .handle)}'`.
+
+## Common patterns
+
+```bash
+# Price tracking — pull current price for a known ASIN
+hasdata amazon-product --asin "$ASIN" --raw | jq '.price'
+
+# Product discovery → details fan-out
+hasdata amazon-search --q "$Q" --raw \
+  | jq -r '.results[].asin' \
+  | head -5 \
+  | xargs -I{} hasdata amazon-product --asin {} --raw
+
+# Compare across marketplaces
+for d in amazon.com amazon.co.uk amazon.de; do
+  echo "=== $d ==="
+  hasdata amazon-product --asin "$ASIN" --domain "$d" --raw \
+    | jq '{currency: .currency, price: .price}'
+done
+```

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

@@ -0,0 +1,227 @@
+# Data enrichment
+
+Enriching a company, domain, or authorized contact list with public data. Use these workflows only for permitted business research or user-authorized contact enrichment, and respect site terms, robots/access controls, privacy law, opt-out obligations, and rate limits.
+
+## SERP first. Web-scraping is the last resort.
+
+`google-serp` is your primary enrichment tool. Reasons:
+
+- **Google has already extracted the structured fields you want.** `.knowledge_graph` carries HQ, founder, founded year, parent company, employees, industry. `.organic_results[]` titles and snippets carry person → role → employer mappings (LinkedIn titles are literally `Name — Role at Company`). `.local_results[]` carry phone/address/hours.
+- **It avoids unnecessary direct access.** Many target sites gate, rate-limit, or restrict scraping. Google's snippets can answer public, high-level questions without rendering the target page.
+- **It's a broad public index.** Quoted queries (`--q '"info@example.com"'`, `--q '"+1 555 123 4567"'`, `--q '"Acme Corp"'`) can find publicly indexed business contact or company references.
+
+Use `google-serp` (or `google-news` for recency, `google-maps` for places, `google-shopping` for products) **first**. Only fall through to `web-scraping` when:
+- A specific field you need isn't in any SERP snippet, AND
+- The target page renders that field server-side or via JS that the scraper can handle, AND
+- The user explicitly needs it and has authority to access it (don't fan out to N web-scraping calls when SERP would have answered N - 0 of them).
+
+The patterns below show the full chain so you understand when to escalate. Most rows in a real CSV stop after step 1 or 2.
+
+---
+
+## Person enrichment
+
+### Step 1 — SERP for role, employer, LinkedIn URL
+
+```bash
+hasdata google-serp --q '"Jane Doe" linkedin' --num 5 --raw \
+  | jq -c '.organic_results[] | select(.link | contains("linkedin.com/in/")) |
+           {title, snippet, link}'
+```
+
+The result usually looks like:
+
+```json
+{
+  "title": "Jane Doe — Senior Engineer at Acme Corp | LinkedIn",
+  "snippet": "San Francisco, CA · 500+ connections · Engineering @ Acme. Previously...",
+  "link": "https://www.linkedin.com/in/janedoe"
+}
+```
+
+You now have role, employer, location, LinkedIn URL, and a connection-count hint — without scraping anything. **Stop here unless a specific extra field is required.**
+
+### Step 2 — Refine with targeted SERP queries
+
+If step 1 didn't carry what you need, ask Google more specifically:
+
+```bash
+# Disambiguate by company
+hasdata google-serp --q '"Jane Doe" "Acme Corp"' --num 10 --raw \
+  | jq -c '.organic_results[] | {title, snippet, link}'
+
+# Other social profiles
+hasdata google-serp --q '"Jane Doe" site:twitter.com OR site:x.com' --num 3 --raw
+hasdata google-serp --q '"Jane Doe" site:github.com' --num 3 --raw
+
+# Past employers / bio paragraphs
+hasdata google-serp --q '"Jane Doe" bio OR background OR experience' --num 5 --raw \
+  | jq -r '.organic_results[].snippet'
+```
+
+### Step 3 — Web-scraping (only if SERP came up short)
+
+When SERP snippets truncated the field you need, or the user explicitly wants full profile content, first confirm the profile is public or the user has authorization to access it:
+
+```bash
+hasdata web-scraping --url "https://www.linkedin.com/in/janedoe" \
+  --output-format markdown --no-screenshot --no-block-resources \
+  --raw | jq -r .markdown
+```
+
+Or for structured fields, AI extraction:
+
+```bash
+hasdata web-scraping --url "https://www.linkedin.com/in/janedoe" \
+  --ai-extract-rules-json '{
+    "headline":   {"type": "string"},
+    "location":   {"type": "string"},
+    "company":    {"type": "string"},
+    "role":       {"type": "string"},
+    "followers":  {"type": "number"},
+    "experience": {"type": "list", "output": {
+      "company":  {"type": "string"},
+      "role":     {"type": "string"},
+      "duration": {"type": "string"}
+    }}
+  }' --raw | jq .
+```
+
+LinkedIn sometimes blocks the public preview; if it does, fall back to step 2 (combining SERP snippets) — it's almost always enough.
+
+### Email lookup
+
+Triangulate, don't promise. Use this only for business contact discovery, user-authorized enrichment, or another legitimate purpose. SERP first, scraping last; never present a guessed personal email as verified.
+
+```bash
+# 1. Has Google already indexed the email anywhere?
+hasdata google-serp --q '"jane.doe@acme.com"' --num 10 --raw \
+  | jq -c '.organic_results[] | {title, snippet, link}'
+
+# 2. What email format does the company use? Look for any indexed @company.com address.
+hasdata google-serp --q 'site:acme.com "@acme.com"' --num 10 --raw \
+  | jq -r '.organic_results[].snippet' \
+  | grep -oE '[A-Za-z0-9._-]+@acme\.com' | sort -u
+
+# 3. Pattern-guess + SERP-verify
+for guess in "jane.doe" "jdoe" "jane" "j.doe" "janed"; do
+  count=$(hasdata google-serp --q "\"$guess@acme.com\"" --num 1 --raw \
+            | jq -r '.organic_results | length')
+  [ "$count" -gt 0 ] && echo "$guess@acme.com  (appears in SERP)"
+done
+
+# 4. Last resort — scrape the company's public contact / about / team pages for emails
+hasdata web-scraping --url "https://acme.com/about" --extract-emails --raw \
+  | jq -r '.emails // [] | .[]'
+```
+
+Always tell the user when an email is a pattern-guess vs. confirmed via SERP/scrape, and avoid collecting personal contact data when the user lacks authorization.
+
+---
+
+## Company enrichment
+
+### Step 1 — SERP knowledge_graph
+
+```bash
+hasdata google-serp --q "Acme Corp" --num 5 --raw | jq '.knowledge_graph // {}'
+```
+
+`.knowledge_graph` typically contains: founder, founded (year), headquarters, parent_organization, ceo, employees (range), revenue, stock_price, industry, products. **For the majority of company enrichment requests, this single call is the entire answer.**
+
+### Step 2 — Targeted SERP for specific fields
+
+```bash
+# Headquarters
+hasdata google-serp --q '"Acme Corp" headquarters' --num 5 --raw \
+  | jq -r '.organic_results[].snippet'
+
+# Funding / acquisition signals
+hasdata google-serp --q '"Acme Corp" raises OR acquires OR acquired OR ipo OR funding' --num 10 --raw \
+  | jq -c '.organic_results[] | {title, snippet, link}'
+
+# Recent news
+hasdata google-news --q "Acme Corp" --gl us --raw \
+  | jq -c '.news_results[] | {title, source: .source.name, date, link}'
+
+# LinkedIn company page
+hasdata google-serp --q '"Acme Corp" site:linkedin.com/company' --num 3 --raw \
+  | jq -c '.organic_results[] | {title, snippet, link}'
+
+# Employee profiles in a specific function/region
+hasdata google-serp \
+  --q 'site:linkedin.com/in "Acme Corp" engineer' --gl us --num 25 --raw \
+  | jq -r '.organic_results[] | "\(.title)\t\(.link)"'
+```
+
+### Step 3 — Web-scraping (only when SERP can't fill a specific field)
+
+```bash
+# Company About page → AI-extract structured fields
+hasdata web-scraping --url "https://acme.com/about" \
+  --ai-extract-rules-json '{
+    "name":         {"type": "string"},
+    "founded":      {"type": "number"},
+    "headquarters": {"type": "string"},
+    "employees":    {"type": "string"},
+    "industry":     {"type": "string"},
+    "description":  {"type": "string"},
+    "products":     {"type": "list"}
+  }' --raw | jq .
+```
+
+Reach for this only when the user wants something SERP can't provide (e.g. mission statement verbatim, full product taxonomy, leadership team page parsed into rows).
+
+---
+
+## CSV row enrichment
+
+For a list of N rows, fan out one or two SERP calls per row. Keep web-scraping out of the loop unless a specific row needs it.
+
+```bash
+# Input: people.csv with one column "name"
+while IFS=, read -r name; do
+  result=$(hasdata google-serp --q "\"$name\" linkedin" --num 1 --raw)
+  linkedin=$(echo "$result" | jq -r '.organic_results[0].link // ""')
+  title=$(echo "$result"    | jq -r '.organic_results[0].title // ""')
+  snippet=$(echo "$result"  | jq -r '.organic_results[0].snippet // ""')
+  printf '%s\t%s\t%s\t%s\n' "$name" "$title" "$snippet" "$linkedin"
+done < people.csv > enriched.tsv
+```
+
+That's it. One SERP call per row, role/employer/LinkedIn extracted from the title and snippet. Add a second SERP call only if a row's first result didn't match (`select(.title | test("\(name)"; "i"))` filtering for confidence).
+
+---
+
+## Reverse-lookup
+
+Always SERP-first with the literal value quoted. Use reverse lookup only for user-authorized investigation, business contact verification, or another legitimate purpose; do not use it for doxxing, stalking, harassment, or collecting private personal data.
+
+```bash
+# Business email → public identity signal
+hasdata google-serp --q '"jane@example.com"' --num 10 --raw \
+  | jq -c '.organic_results[] | {title, snippet, link}'
+
+# Business phone → owner / business
+hasdata google-serp --q '"+1 555 123 4567"' --num 10 --raw
+# Combine with yelp-search / yellowpages-search if it's a business number.
+
+# Domain → company
+hasdata google-serp --q "site:example.com" --num 5 --raw \
+  | jq '.organic_results[0].title'
+hasdata google-serp --q "Acme Corp" --num 5 --raw | jq '.knowledge_graph // {}'
+```
+
+Only scrape the domain (`web-scraping --url "https://example.com"`) when you specifically need the homepage's body text.
+
+---
+
+## Tips for reliable enrichment
+
+- **Always quote names and other multi-token strings** — `"Jane Doe"` matches the exact person; `Jane Doe` matches noise.
+- **Use `site:` aggressively** — `site:linkedin.com/in/`, `site:linkedin.com/company/`, `site:github.com`, `site:crunchbase.com`. Google's `site:` is the cheapest way to scope an enrichment search.
+- **Read the `.knowledge_graph`** before doing anything else for a company. If it's populated, you're often done.
+- **AI-extract over CSS selectors** when you do need to scrape — LinkedIn / Crunchbase / About-page markup changes constantly; AI extraction with field names + descriptions survives layout churn.
+- **Cross-source verify** — never enrich from a single source. If LinkedIn's title says "Acme Corp" and a `--q '"Jane Doe" "Acme Corp"'` SERP corroborates with multiple results, confidence is high.
+- **Mark guesses** — pattern-guessed emails, inferred locations, single-source roles should be flagged to the user as unverified.
+- **Respect privacy and authorization** — do not collect or infer personal contact details without a legitimate purpose and user authority.

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

@@ -0,0 +1,84 @@
+# Jobs reference
+
+Subcommands: `indeed-listing`, `indeed-job`, `glassdoor-listing`, `glassdoor-job`. Indeed: 5 credits. Glassdoor: 10 credits.
+
+`*-listing` searches by query/location; `*-job` deep-dives a specific posting by URL or ID.
+
+---
+
+## indeed-listing
+
+```bash
+hasdata indeed-listing \
+  --query "backend engineer" --location "Remote" \
+  [--days-since-posted 7] [--job-type fulltime|parttime|contract|temporary|internship] \
+  [--remote] [--page 1] \
+  --raw | jq '.jobs[] | {title, company, location, posted, salary, url}'
+```
+
+Other flags worth knowing:
+- `--salary-min N` / `--salary-max N`
+- `--experience-level entry|mid|senior`
+- `--sort relevance|date`
+- `--country us|gb|ca|de|fr|...`
+
+## indeed-job
+
+```bash
+hasdata indeed-job --url "https://www.indeed.com/viewjob?jk=..." --raw | jq .
+```
+
+Or `--job-key JK`. Returns full description, company info, benefits, hiring insights, similar jobs.
+
+## glassdoor-listing
+
+```bash
+hasdata glassdoor-listing --keyword "data scientist" --location "Boston" --raw \
+  | jq '.jobs[] | {title, employer, salary_estimate, rating}'
+```
+
+Glassdoor includes employer ratings and salary estimates per result. Use this when the user cares about employer reputation alongside the role.
+
+## glassdoor-job
+
+```bash
+hasdata glassdoor-job --url "https://www.glassdoor.com/Job/jobs.htm?...JV=..." --raw | jq .
+```
+
+Returns full posting plus employer rating breakdown, recent reviews, salary estimate range, interview difficulty.
+
+---
+
+## Non-obvious use cases
+
+- **Salary-negotiation research** — `indeed-listing --query ROLE --location CITY` then `jq '[.jobs[].salary | select(.)] | sort_by(.min)'` to build a defensible range before a comp conversation.
+- **"Should I move for this job?"** — same role across 3–5 cities; compare median salaries to local cost of living.
+- **Hiring-pattern intel on a competitor** — `indeed-listing --query "company:NAME"` (or use `glassdoor-listing` filtered by employer) returns recent postings; surfaces what teams are growing, what stack they're on, what locations they're in.
+- **"Are they really hiring or is this a ghost job?"** — `indeed-job --url X --raw | jq '.posted_at'`. Postings older than 60 days that haven't been refreshed are often ghosts.
+- **Stack popularity by region** — `indeed-listing --query "Rust" --location "Berlin"` vs `--location "San Francisco"` to compare absolute postings and salary deltas for a specific tech.
+- **Career-pivot research** — `indeed-listing --query "TARGET ROLE" --raw | jq -r '.jobs[].description'` then summarize the most-required skills with an LLM. Reveals the actual gap, not what bootcamps claim.
+- **Employer reputation deep-dive** — `glassdoor-listing` returns ratings inline; `glassdoor-job` returns recent reviews + interview difficulty. Use before applying or accepting.
+- **Remote-job filter** — `--remote` on `indeed-listing` cuts to fully-remote postings; use `--country gb` etc. to find role markets that are remote-friendly outside the US.
+- **Visa-friendly employer detection** — search `indeed-listing --query "ROLE H1B sponsorship"` or `--query "ROLE relocation"` — listings that mention these are more likely to support visa transfers.
+- **Internship-only filter** — `--job-type internship` on `indeed-listing` for early-career searches.
+- **Salary-band reverse engineering** — Glassdoor's `salary_estimate` is an estimate; cross-check by sampling 5–10 indeed postings for the same role/title in the same city and computing your own median.
+- **"Who's leaving Company X?"** — `glassdoor-listing --keyword "previously at: COMPANY"` is a stretch query but sometimes surfaces postings where ex-employees describe their transition.
+- **Detect layoffs before the news** — sudden surge in `indeed-listing --query "ex-COMPANY"` postings in a region often precedes the announcement.
+- **Negotiation prep — interview difficulty** — `glassdoor-job --url X --raw | jq '.interview_difficulty, .interview_experiences[]'` shows how previous candidates rated the process.
+
+## Common patterns
+
+```bash
+# Salary distribution for a role
+hasdata indeed-listing --query "senior python developer" --location "New York, NY" \
+  --raw | jq '[.jobs[].salary | select(. != null)] | unique'
+
+# Compare same role on both platforms
+for src in indeed-listing glassdoor-listing; do
+  echo "=== $src ==="
+  hasdata "$src" --query "platform engineer" --location "SF" --raw \
+    | jq '.jobs[:5][] | {title, company: (.company // .employer), location}'
+done
+```
+
+Start with Indeed for breadth; escalate to Glassdoor when employer ratings or interview-difficulty data are needed.

package/bundled-skills/hasdata-cli/references/local-business.md

@@ -0,0 +1,123 @@
+# Local-business / maps reference
+
+Subcommands: `google-maps`, `google-maps-place`, `google-maps-reviews`, `google-maps-contributor-reviews`, `google-maps-photos`, `google-maps-posts`, `yelp-search`, `yelp-place`, `yellowpages-search`, `yellowpages-place`. 5 credits each (10 for `google-maps-posts` and YellowPages).
+
+---
+
+## google-maps
+
+```bash
+hasdata google-maps --q "coffee" --ll "@30.2672,-97.7431,14z" --raw | jq '.local_results[]'
+```
+
+Required: `--q TEXT`. Other useful flags:
+- `--ll "@LAT,LNG,ZOOMz"` — center point + zoom (Google's `ll` parameter)
+- `--gl us|gb|...` — country
+- `--hl en|es|...` — language
+- `--type search|place` — search vs. specific place lookup
+- `--data` / `--cid` / `--fid` — Google identifiers (advanced)
+
+Per-result: `title`, `place_id`, `rating`, `reviews`, `address`, `phone`, `website`, `types[]`, `gps_coordinates`.
+
+## google-maps-place
+
+```bash
+hasdata google-maps-place --place-id "ChIJ..." --raw | jq .
+```
+
+Single place: full details, hours, popular times, attributes.
+
+## google-maps-reviews
+
+```bash
+hasdata google-maps-reviews --place-id "ChIJ..." [--sort newest|highest|lowest] --raw \
+  | jq '.reviews[] | {author, rating, date, snippet}'
+```
+
+For pagination, the response includes a `next_page_token` — pass via `--next-page-token`.
+
+## google-maps-contributor-reviews
+
+Reviews authored by a specific Google contributor (by `--contributor-id`). Useful for local-guide analysis.
+
+## google-maps-photos
+
+```bash
+hasdata google-maps-photos --place-id "ChIJ..." --raw
+```
+
+Returns photo URLs by category (interior, exterior, food, etc.).
+
+## google-maps-posts (10 credits)
+
+```bash
+hasdata google-maps-posts --place-id "ChIJ..." [--hl en] [--next-page-token TOKEN] --raw \
+  | jq '.posts[] | {postedAt, description, cta, postUrl}'
+```
+
+Posts are the business-owner publications shown on a Maps listing: offers, events, holiday hours, announcements. Either `--place-id` **or** `--data-id` is required.
+
+Per-post fields (verified live): `postId`, `locationId`, `title`, `description`, `image`, `cta` (object with `label` + `url`), `createdAt` (ISO), `postedAt` (human-readable), `shareUrl`, `postUrl`. Use `pagination.nextPageToken` for older posts.
+
+---
+
+## yelp-search
+
+```bash
+hasdata yelp-search --query "italian" --location "Brooklyn, NY" [--page 1] --raw \
+  | jq '.businesses[] | {name, rating, review_count, price, categories}'
+```
+
+## yelp-place
+
+```bash
+hasdata yelp-place --url "https://www.yelp.com/biz/SLUG" --raw | jq .
+```
+
+Single business: full details, hours, top reviews, photos, attributes.
+
+## yellowpages-search
+
+```bash
+hasdata yellowpages-search --search-terms "plumber" --geo-location-terms "Atlanta, GA" --raw
+```
+
+## yellowpages-place
+
+```bash
+hasdata yellowpages-place --url "https://www.yellowpages.com/atlanta-ga/mip/..." --raw
+```
+
+---
+
+## Non-obvious use cases
+
+- **Sales-lead research** — `google-maps --q "INDUSTRY" --ll "@LAT,LNG,12z"` to enumerate businesses, then `xargs` into `google-maps-place` for public phone/website details. Use email collection only for legitimate business outreach with opt-out, privacy-law, and rate-limit controls.
+- **Reputation monitoring** — `google-maps-reviews --place-id X --sort lowest` returns the worst reviews first; great for surfacing crisis signals fast. Run weekly to detect new 1-star drops.
+- **"Is this business open?"** — `google-maps-place --place-id X --raw | jq '.hours'` for current hours; also surfaces `permanently_closed` status.
+- **Verify an address user gave you** — `google-maps --q "BUSINESS NAME, CITY" --raw | jq '.local_results[0].address'`. Don't trust user-provided addresses for high-stakes actions (mailing, payments).
+- **Public business contact lookup** — `google-maps-place` includes phone and website; `web-scraping --url WEBSITE --extract-emails` returns emails parsed from the homepage. Use only for public business contact channels and disclose uncertainty.
+- **Competitive-density mapping** — `google-maps --q "coffee shop" --ll "@LAT,LNG,Zz"` at varying zoom levels; aggregate `.local_results[]` into a CSV with addresses + ratings to find under-served zones.
+- **Service-area validation** — chain `yelp-search --location "CITY"` for a few cities to confirm a business with the same name covers them.
+- **Find recently opened businesses** — `google-maps-place` returns `description.years_in_business` and posts/updates timestamps; sort.
+- **Negative-review sample for product analysis** — `yelp-place --url X --raw | jq '.reviews[] | select(.rating <= 2)'`; useful as input to a "what do customers complain about" summary.
+- **Photo-mining for visual docs** — `google-maps-photos --place-id X` returns categorized photo URLs (interior, food, exterior). Useful when the user needs an image and doesn't want to rely on `google-images`.
+- **Local-guide credibility** — `google-maps-contributor-reviews --contributor-id X` shows everything a specific reviewer wrote, useful for filtering out shilling/fake reviewers when their pattern is suspicious.
+- **YellowPages for B2B niches** — service-business categories (plumbers, electricians, lawyers) are often better indexed by YellowPages than Yelp; try both when one comes up empty.
+- **Cross-platform reputation diff** — same business name + city via `yelp-search` and `google-maps` to compare ratings across platforms (gap often signals fake reviews on one).
+- **Promo / event surveillance** — `google-maps-posts --place-id X` surfaces current offers, holiday hours, and limited-time events the business is actively pushing. Cheaper signal than scraping the website, and the `cta.url` typically links to the canonical landing page.
+- **Detect a business about to relaunch / rebrand** — sudden burst of new `google-maps-posts` after months of silence usually precedes a re-grand-opening or ownership change.
+
+## Common patterns
+
+```bash
+# Build a directory: search → fan out to per-place details
+hasdata google-maps --q "yoga studios" --ll "@30.27,-97.74,12z" --raw \
+  | jq -r '.local_results[].place_id' \
+  | head -10 \
+  | xargs -I{} hasdata google-maps-place --place-id {} --raw
+
+# Sentiment / review analysis
+hasdata google-maps-reviews --place-id "$PID" --sort lowest --raw \
+  | jq '.reviews[] | {rating, snippet}'
+```

package/bundled-skills/hasdata-cli/references/real-estate.md

@@ -0,0 +1,126 @@
+# Real-estate reference
+
+Subcommands: `zillow-listing`, `zillow-property`, `redfin-listing`, `redfin-property` — 5 credits each.
+
+For short-term rentals (Airbnb), hotels (Booking) and flights, see `travel.md`.
+
+`*-listing` is for filtered searches; `*-property` is a single-property deep dive.
+
+---
+
+## zillow-listing
+
+```bash
+hasdata zillow-listing --keyword "Austin, TX" --type forSale [filters] --raw | jq '.results[]'
+```
+
+Required:
+- `--keyword "City, ST"` (default: `New York, NY`)
+- `--type forSale|forRent|sold` (default: `forSale`)
+
+Price / size (bracketed pairs, kept as floats):
+- `--price-min N --price-max N`
+- `--beds-min N --beds-max N`
+- `--baths-min N --baths-max N`
+- `--square-feet-min N --square-feet-max N`
+- `--lot-size-min N --lot-size-max N`
+- `--year-built-min N --year-built-max N`
+- `--hoa N` — max HOA fee
+- `--parking-spots-min N`
+
+Array filters (enum-validated, lowercase camelCase values):
+- `--home-types house|townhome|multiFamily|condo|lot|apartment|manufactured` (repeatable)
+- `--pets allowsLargeDogs|allowsSmallDogs|allowsCats` (repeatable)
+- `--other-amenities ac|pool|waterfront|onsiteParking|inUnitLaundry|acceptZillowApplications|incomeRestricted|apartmentCommunity` (repeatable)
+- `--views city|mountain|park|water` (repeatable)
+- `--basement finished|unfinished` (repeatable)
+- `--property-status comingSoon|acceptingBackupOffers|pendingAndUnderContract` (repeatable)
+- `--listing-publish-options ownerPosted|agentListed|newConstruction|foreclosures|auctions|foreclosed|preForeclosures` (repeatable)
+- `--tours open|3d` (repeatable)
+
+Booleans:
+- `--must-have-garage` — only listings with a garage
+- `--single-story-only`
+- `--hide55plus-communities`
+
+Other:
+- `--listing-type byAgent|byOwner`
+- `--days-on-zillow 1|7|14|30|90|6m|12m|24m|36m`
+- `--keywords "open floor plan"` — refinement keywords (matches in description)
+- `--move-in-date 2026-06-01`
+- `--page N` — pagination
+- `--sort verifiedSource|homesForYou|priceHighToLow|priceLowToHigh|paymentHighToLow|paymentLowToHigh|newest|bedrooms|bathrooms|squareFeet|lotSize`
+
+### Examples
+
+```bash
+# Family home, mid-market, sorted cheapest first
+hasdata zillow-listing \
+  --keyword "Austin, TX" --type forSale \
+  --price-min 400000 --price-max 900000 \
+  --beds-min 3 --beds-max 5 --baths-min 2 \
+  --home-types house --home-types townhome \
+  --sort priceLowToHigh --raw | jq '.results[] | {address, price, beds, baths}'
+
+# Pet-friendly rental
+hasdata zillow-listing \
+  --keyword "Seattle, WA" --type forRent \
+  --price-max 4000 \
+  --pets allowsSmallDogs --pets allowsCats \
+  --parking-spots-min 1 --must-have-garage \
+  --raw
+
+# Recently sold comps
+hasdata zillow-listing \
+  --keyword "Miami, FL" --type sold \
+  --square-feet-min 1500 --square-feet-max 4000 \
+  --year-built-min 2000 --year-built-max 2020 \
+  --days-on-zillow 12m --sort newest --raw
+```
+
+Bracketed query params (`price[max]`, `homeTypes[]`, `yearBuilt[min]`) are handled by the CLI — pass the kebab-case flags shown above, not the raw API names.
+
+## zillow-property
+
+```bash
+hasdata zillow-property --url "https://www.zillow.com/homedetails/.../123_zpid/" --raw | jq .
+```
+
+Or with `--zpid <ID>`. Returns full property details (photos, history, schools, taxes, walk-score, etc.).
+
+## redfin-listing
+
+Similar shape to `zillow-listing` but Redfin's enums differ. Run `hasdata redfin-listing --help` for the exact list. Common pattern:
+
+```bash
+hasdata redfin-listing --location "San Francisco, CA" --status forSale \
+  --min-price 800000 --max-price 1500000 \
+  --min-beds 2 --raw
+```
+
+## redfin-property
+
+```bash
+hasdata redfin-property --url "https://www.redfin.com/CA/San-Francisco/.../home/12345" --raw
+```
+
+---
+
+## Non-obvious use cases
+
+- **Investment screening** — combine `--type sold` + `--days-on-zillow 12m` + `--year-built-min` + `--lot-size-min` to surface flip / value-add candidates. Then `xargs` into `zillow-property` for ARV analysis.
+- **Tax-appeal comps** — `--type sold --keyword "ZIP CODE" --days-on-zillow 12m` filtered to your home's beds/baths/sqft band gives recent sales the assessor used; export to CSV with `jq -r '.results[] | [.address, .price, .beds, .baths, .squareFootage, .soldDate] | @csv'`.
+- **Appraiser comp pull** — same trick, narrower square-footage and same year-built band.
+- **Motivated-seller signal** — `--type forSale --days-on-zillow 90` returns listings that have lingered. Often willing to negotiate.
+- **Pre-relocation neighborhood scan** — run the same `--type forRent` filter across 5–10 neighborhoods, dump rent distributions with `jq '.results[].price'`, eyeball cost differences before booking visits.
+- **STR-vs-LTR feasibility** — pair `airbnb-listing` (see `travel.md`) for nightly rates with `zillow-listing --type forSale` for purchase price in the same area; compute gross yield client-side.
+- **HOA filter** — `--hoa N` caps fee; useful for buyers who want max payment ceilings.
+- **School-driven house hunt** — `zillow-property` returns school ratings; filter `zillow-listing` results down by walking each property and keeping those with rating ≥ X.
+- **Open-houses this weekend** — Zillow tags open-house listings; check `.results[].openHouseTimes` for upcoming slots.
+- **3D-tour / virtual-tour-only filter** — `--tours 3d` → only listings with virtual tours. Useful for remote / international buyers.
+- **Pet-friendly rentals at scale** — `--pets allowsLargeDogs --pets allowsCats` for multi-pet households. Pairs well with `--keyword` for specific neighborhoods.
+- **Foreclosure and pre-foreclosure leads** — `--listing-publish-options foreclosures --listing-publish-options preForeclosures`.
+- **Non-traditional listing types** — `--listing-type byOwner` for FSBO; `--listing-type byAgent` for agent-listed (default mix).
+- **Move-in date constraint** — `--move-in-date YYYY-MM-DD` for rental searches with a hard timing requirement.
+- **Bulk address verification** — pipe a list of property URLs through `zillow-property` to confirm they resolve and pull the canonical address Zillow uses.
+- **Verify a Redfin/Zillow listing is real** — `redfin-property --url X --raw | jq .status` to confirm it hasn't been pulled.