mercury-agent 0.4.5

package/examples/extensions/web-search/skill/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: web-search
+description: Search public websites for real-world things — flights, hotels, car rentals, cars for purchase, and apartments/rentals. No credentials needed. Trigger when the user asks to find, compare, or book flights, accommodation, rental cars, used/new cars, or apartments. Uses headless browser automation (pinchtab) to navigate live sites and return real results.
+---
+
+# Web Search
+
+Search public websites for travel, accommodation, vehicles, and real estate using the headless browser (pinchtab). No API keys or credentials required.
+
+## Prerequisite
+
+Before any search, ensure the browser is running:
+
+```bash
+pinchtab_ensure || exit 1
+```
+
+`pinchtab_ensure` is defined and injected by the pinchtab extension. If it is not already defined in your shell session, refer to the pinchtab skill for the full definition.
+
+## Dispatch Table
+
+Identify the search category from the user's intent, then read the corresponding reference file before proceeding.
+
+| User intent keywords | Category | Reference file |
+|---|---|---|
+| flight, fly, airline, plane ticket | Flights | `references/flights.md` |
+| hotel, hostel, stay, accommodation, resort, inn | Hotels | `references/hotels.md` |
+| rent a car, car hire, rental car, hire car | Car rental | `references/car-rental.md` |
+| buy a car, used car, new car, car for sale | Car purchase | `references/car-purchase.md` |
+| apartment, flat, rent apartment, house for rent/sale, real estate | Apartments | `references/apartments.md` |
+
+**Always read the reference file for the matched category before navigating.** It contains the site selection rationale, exact URL format, and step-by-step workflow.
+
+## Parameter Collection
+
+Do not navigate to any site until you have all required parameters. Ask the user for anything missing.
+
+### Flights (required: origin, destination, departure date)
+- Origin airport or city
+- Destination airport or city
+- Departure date
+- Return date (ask if not given — confirm one-way only if explicitly stated)
+- Passengers: number of adults; children with ages (ages affect pricing); infants
+- Cabin class: economy / premium economy / business / first (default: economy)
+- Nonstop only? (default: show all; apply filter if requested)
+- Sort by: cheapest / fastest / best (default: cheapest)
+
+### Hotels (required: city, check-in date, check-out date)
+- City or area
+- Check-in and check-out dates
+- Number of adults and children (with ages if children)
+- Number of rooms (default: 1)
+- Star rating or price range (optional)
+- Sort by: lowest price / rating / distance (default: lowest price)
+
+### Car rental (required: pickup location, pickup date, dropoff date)
+- Pickup location (city name or airport IATA code)
+- Pickup date and time
+- Dropoff date and time
+- Same location dropoff? (if not, ask for dropoff location)
+- Driver age (under-25 surcharges vary by provider)
+- Car category preference: economy / compact / SUV / etc. (optional)
+
+### Car purchase (required: make/model or open search, location/country)
+- Make and/or model (or open description e.g. "any SUV")
+- New or used
+- Maximum price or price range
+- Location / country (determines which site to use)
+- Maximum mileage (for used cars)
+- Year range (optional)
+
+### Apartments (required: city, rent or buy, short-term or long-term)
+- City or neighbourhood
+- Rent or buy
+- Short-term (nightly, like Airbnb) or long-term (monthly lease)?
+- Price range (per night or per month)
+- Number of bedrooms
+- Move-in / available-from date
+
+## Output Format
+
+Present results as a numbered list. Limit to top 5–10 unless the user requests more.
+
+```
+1. [Airline / Hotel name / Car type / Listing title]
+   Price: [amount + currency]
+   Details: [duration + stops, or rating + location, or mileage + year, etc.]
+   Dates: [if applicable]
+   Link: [URL if visible in the page]
+
+2. ...
+```
+
+Always state the site used and the search parameters at the top of the reply so the user can verify.
+
+## Error Handling
+
+- **CAPTCHA or bot block**: note it, try the fallback site listed in the reference file.
+- **Empty results**: try relaxing one constraint (e.g. remove nonstop-only filter, expand dates ±1 day, widen price range). Inform the user what was relaxed.
+- **Page timeout / snapshot failure**: retry once with an additional `sleep 5` before the snapshot. If it fails again, report the error and the last output.
+- **Consent banner blocking content**: find the dismiss/accept button ref via `pinchtab snap -i -c` and click it, then re-navigate.
+- **Max cycles**: do not loop more than 3 interaction cycles on a single page without reporting progress to the user.
+
+## Token Efficiency
+
+Match the pinchtab command to the task:
+
+| Task | Command | ~Tokens |
+|---|---|---|
+| Read result prices/names | `pinchtab text` | ~800 |
+| Find filter controls to click | `pinchtab snap -i -c` | ~3,600 |
+| Full page understanding | `pinchtab snap` | ~10,500 |
+
+Always start with `pinchtab text`. Only escalate to `snap -i -c` when you need to interact with a filter or button. Never use full `snap` for this skill.

package/examples/extensions/web-search/skill/references/apartments.md

@@ -0,0 +1,178 @@
+# Apartments Reference
+
+## Branch: Short-Term vs Long-Term
+
+**Always confirm before navigating:**
+- **Short-term** = nightly rental (Airbnb-style, days/weeks, travel or vacation)
+- **Long-term** = monthly lease or purchase (living, relocation)
+
+---
+
+## Short-Term: Airbnb (primary)
+
+**Why**: Best accessibility tree for short-term rentals, reliable URL deep-linking, no consent banners.
+
+### URL Construction
+
+```
+https://www.airbnb.com/s/{CITY}/homes?checkin={CHECKIN}&checkout={CHECKOUT}&adults={ADULTS}&children={CHILDREN}&min_bedrooms={BEDROOMS}&price_max={NIGHTLY_MAX}
+```
+
+| Placeholder | Format | Example |
+|---|---|---|
+| `{CITY}` | URL-encoded city | `Bangkok`, `Tel+Aviv` |
+| `{CHECKIN}` | YYYY-MM-DD | `2026-11-01` |
+| `{CHECKOUT}` | YYYY-MM-DD | `2026-11-22` |
+| `{ADULTS}` | integer | `2` |
+| `{CHILDREN}` | integer | `2` |
+| `{BEDROOMS}` | integer | `2` |
+| `{NIGHTLY_MAX}` | integer (USD) | `150` |
+
+**Worked example — Bangkok, Nov 1–22, 2 adults + 2 children, 2+ bedrooms:**
+```
+https://www.airbnb.com/s/Bangkok/homes?checkin=2026-11-01&checkout=2026-11-22&adults=2&children=2&min_bedrooms=2
+```
+
+### Workflow
+
+```bash
+pinchtab_ensure || exit 1
+pinchtab nav "https://www.airbnb.com/s/Bangkok/homes?checkin=2026-11-01&checkout=2026-11-22&adults=2&children=2&min_bedrooms=2"
+sleep 5   # Airbnb is React-heavy — needs longer render time
+pinchtab text
+```
+
+---
+
+## Short-Term Fallback: Booking.com Apartments
+
+Use when Airbnb results are sparse or user prefers hotel-apartment hybrids.
+
+```
+https://www.booking.com/searchresults.html?ss={CITY}&checkin={CHECKIN}&checkout={CHECKOUT}&group_adults={ADULTS}&group_children={CHILDREN}&age={AGE1}&age={AGE2}&nflt=ht_id%3D201%3Bht_id%3D220
+```
+(`ht_id=201` = apartments; `ht_id=220` = holiday homes — include both)
+
+```bash
+pinchtab nav "https://www.booking.com/searchresults.html?ss=Bangkok&checkin=2026-11-01&checkout=2026-11-22&group_adults=2&group_children=2&age=7&age=3&nflt=ht_id%3D201%3Bht_id%3D220"
+sleep 4
+pinchtab text
+```
+
+**Known issue — consent banner**: If `pinchtab text` shows no results, run `pinchtab snap -i -c`, find the "Accept" button ref, click it, wait 2s, then re-navigate.
+
+---
+
+## Long-Term: Site Selection by Region
+
+| Region | Rent | Buy |
+|---|---|---|
+| Israel | Yad2 | Yad2 |
+| UK | Rightmove | Rightmove |
+| Spain / Italy / Portugal | Idealista | Idealista |
+| France | SeLoger | SeLoger |
+| USA | Zillow | Zillow |
+| Germany | ImmoScout24 | ImmoScout24 |
+| International | Airbnb (monthly) | — |
+
+---
+
+## Yad2 — Long-Term (Israel)
+
+```
+https://www.yad2.co.il/realestate/rent?city={CITY_ID}&rooms={MIN_ROOMS}-{MAX_ROOMS}&price={MIN}-{MAX}
+```
+
+For open search in Tel Aviv:
+```
+https://www.yad2.co.il/realestate/rent?topArea=2&area=1
+```
+(topArea=2, area=1 = Tel Aviv district)
+
+```bash
+pinchtab nav "https://www.yad2.co.il/realestate/rent?topArea=2&area=1"
+sleep 4
+pinchtab text
+```
+
+**Note**: Results are in Hebrew. Extract prices (numbers with ₪), room counts, and neighbourhood names.
+
+---
+
+## Rightmove — Long-Term (UK)
+
+```
+https://www.rightmove.co.uk/property-to-rent/find.html?searchType=RENT&locationIdentifier=REGION%5E{ID}&maxPrice={MAX}&minBedrooms={BEDS}
+```
+
+For a city-level search without a region ID, use the simpler form:
+```
+https://www.rightmove.co.uk/property-to-rent/find.html?searchType=RENT&searchLocation={CITY}&maxPrice={MAX_PCM}&minBedrooms={BEDS}
+```
+
+```bash
+pinchtab nav "https://www.rightmove.co.uk/property-to-rent/find.html?searchType=RENT&searchLocation=London&maxPrice=2000&minBedrooms=2"
+sleep 4
+pinchtab text
+```
+
+---
+
+## Zillow — Long-Term (USA)
+
+```
+https://www.zillow.com/homes/for_rent/{CITY}/?searchQueryState={"pagination":{},"mapBounds":{},"filterState":{"price":{"max":{MAX}},"beds":{"min":{BEDS}}}}
+```
+
+Simpler URL (Zillow also accepts natural-language city in the path):
+```
+https://www.zillow.com/homes/for_rent/New-York,-NY/
+```
+
+```bash
+pinchtab nav "https://www.zillow.com/homes/for_rent/New-York,-NY/"
+sleep 5   # Zillow is JS-heavy
+pinchtab text
+```
+
+---
+
+## Idealista — Long-Term (Spain, Italy, Portugal)
+
+```
+https://www.idealista.com/en/alquiler-viviendas/{CITY_SLUG}-{PROVINCE}/con-{ROOMS}-habitaciones,precio-hasta-{MAX}/
+```
+
+**Known issue**: Idealista occasionally shows an anti-bot challenge on first load. If `pinchtab text` shows a Cloudflare page:
+1. Wait 10 seconds: `sleep 10`
+2. Retry `pinchtab text`
+3. If still blocked, try Airbnb monthly as fallback
+
+---
+
+## Airbnb Monthly (International Long-Term Fallback)
+
+Airbnb supports monthly stays with discounted rates. Use as a universal long-term fallback:
+
+```
+https://www.airbnb.com/s/{CITY}/homes?checkin={START}&checkout={END}&adults={ADULTS}&children={CHILDREN}&min_bedrooms={BEDS}&monthly_length=1
+```
+
+---
+
+## Result Extraction
+
+From `pinchtab text`, extract per listing:
+- Property description (studio, 1BR, 2BR, house, etc.)
+- Price (per night for short-term; per month for long-term; or asking price for purchase)
+- Location / neighbourhood
+- Key amenities if visible (pool, parking, A/C)
+- Link or listing ID if visible
+
+---
+
+## Token Efficiency
+
+- `pinchtab text` is sufficient to read listing summaries.
+- Use `pinchtab snap -i -c` only for interacting with price/bedroom filters.
+- Airbnb and Booking load slower than Google products — always use `sleep 5` minimum.

package/examples/extensions/web-search/skill/references/car-purchase.md

@@ -0,0 +1,132 @@
+# Car Purchase Reference
+
+## Site Selection by Region
+
+The right site depends on the user's location. **Always ask or infer the country before navigating.**
+
+| Region | Primary site | Fallback |
+|---|---|---|
+| Europe (excl. UK) | AutoScout24 | Mobile.de (Germany), LeBonCoin (France) |
+| Israel | Yad2 | AutoScout24 |
+| United Kingdom | AutoTrader UK | Gumtree |
+| United States / Canada | CarGurus | Cars.com |
+| Australia | CarsGuide | Drive.com.au |
+
+---
+
+## AutoScout24 (Europe — primary)
+
+**Why**: Strong EU-wide inventory, clean URL filtering, accessible result cards with price, mileage, year.
+
+### URL Construction
+
+```
+https://www.autoscout24.com/lst/{MAKE}/{MODEL}?atype=C&cy={COUNTRY_CODE}&pricefrom={MIN}&priceto={MAX}&kmfrom={MIN_KM}&kmto={MAX_KM}&fregfrom={YEAR_FROM}&fregto={YEAR_TO}&sort=price&desc=0
+```
+
+| Placeholder | Format / Values | Example |
+|---|---|---|
+| `{MAKE}` | lowercase make slug | `toyota`, `bmw`, `volkswagen` |
+| `{MODEL}` | lowercase model slug | `corolla`, `3-series`, `golf` |
+| `{COUNTRY_CODE}` | ISO 2-letter | `IL`, `DE`, `FR`, `IT`, `ES`, `NL` |
+| `{MAX}` | integer (EUR) | `20000` |
+| `{MAX_KM}` | integer | `150000` |
+| `{YEAR_FROM}` | 4-digit year | `2018` |
+| `sort=price&desc=0` | cheapest first | (keep as-is) |
+
+**Worked example — used Toyota Corolla in Israel, under €20k, under 150k km, from 2018:**
+```
+https://www.autoscout24.com/lst/toyota/corolla?atype=C&cy=IL&priceto=20000&kmto=150000&fregfrom=2018&sort=price&desc=0
+```
+
+**Open search (no specific model):**
+```
+https://www.autoscout24.com/lst?atype=C&cy=IL&bodytype=3&priceto=20000&sort=price&desc=0
+```
+(`bodytype=3` = SUV; omit for any body type)
+
+### Workflow
+
+```bash
+pinchtab_ensure || exit 1
+pinchtab nav "https://www.autoscout24.com/lst/toyota/corolla?atype=C&cy=IL&priceto=20000&kmto=150000&fregfrom=2018&sort=price&desc=0"
+sleep 4
+pinchtab text
+```
+
+---
+
+## Yad2 (Israel — primary for local listings)
+
+**Why**: Dominant Israeli classifieds platform; more local dealer and private listings than AutoScout24 for Israel.
+
+### URL Construction
+
+```
+https://www.yad2.co.il/vehicles/cars?manufacturer={MANUFACTURER_ID}&model={MODEL_ID}&price={MIN}-{MAX}&year={YEAR_FROM}-{YEAR_TO}&km={MIN_KM}-{MAX_KM}
+```
+
+Yad2 uses numeric IDs for manufacturer and model. For open search without a specific make:
+```
+https://www.yad2.co.il/vehicles/cars?price=0-100000&year=2018-2026
+```
+
+**Note**: Yad2 is in Hebrew. The `pinchtab text` output will be in Hebrew. Extract prices (numbers), years, and mileage numerically. Translate model names as needed.
+
+### Workflow
+
+```bash
+pinchtab_ensure || exit 1
+pinchtab nav "https://www.yad2.co.il/vehicles/cars?price=0-100000&year=2018-2026"
+sleep 4
+pinchtab text
+```
+
+---
+
+## AutoTrader UK
+
+```
+https://www.autotrader.co.uk/car-search?make={MAKE}&model={MODEL}&price-to={MAX}&year-from={YEAR}&maximum-mileage={MAX_KM}&sort=price-asc
+```
+
+```bash
+pinchtab nav "https://www.autotrader.co.uk/car-search?make=TOYOTA&model=COROLLA&price-to=20000&year-from=2018&maximum-mileage=100000&sort=price-asc"
+sleep 4
+pinchtab text
+```
+
+---
+
+## CarGurus (USA / Canada)
+
+```
+https://www.cargurus.com/Cars/new/nl_New_Cars.d?zip={ZIP}&sortDir=ASC&sortType=PRICE&maxPrice={MAX}&minYear={YEAR}&makes[]={MAKE}
+```
+
+For used cars, use `nl_Used_Cars` instead of `nl_New_Cars`. Without a ZIP code, results show national listings.
+
+```bash
+pinchtab nav "https://www.cargurus.com/Cars/new/nl_Used_Cars.d?sortDir=ASC&sortType=PRICE&maxPrice=20000&minYear=2018&makes[]=Toyota"
+sleep 4
+pinchtab text
+```
+
+---
+
+## Result Extraction
+
+From `pinchtab text`, extract per listing:
+- Make and model
+- Year
+- Mileage (km or miles)
+- Price (and currency)
+- Location (city or dealership name)
+- Fuel type / transmission (if visible)
+
+---
+
+## Token Efficiency
+
+- `pinchtab text` is sufficient for reading classified listings.
+- Use `pinchtab snap -i -c` only if you need to interact with filters (e.g. adjust mileage slider, select body type).

package/examples/extensions/web-search/skill/references/car-rental.md

@@ -0,0 +1,113 @@
+# Car Rental Reference
+
+## Primary site: Kayak Cars
+
+**Why Kayak Cars:**
+- Aggregates multiple rental providers (Hertz, Avis, Enterprise, local agencies) in one search
+- IATA airport codes work as pickup/dropoff locations — clean URL deep-linking
+- Price cells labelled with provider name + car category + daily and total rate
+- No login required for searching
+
+**Fallback: Rentalcars.com** — better international coverage outside major airports. See below.
+
+---
+
+## URL Construction
+
+```
+https://www.kayak.com/cars/{LOCATION}/{PICKUP_DATE}-{PICKUP_TIME}h/{DROPOFF_DATE}-{DROPOFF_TIME}h
+```
+
+| Placeholder | Format | Example |
+|---|---|---|
+| `{LOCATION}` | IATA airport code or city name | `TLV` or `Bangkok` |
+| `{PICKUP_DATE}` | YYYY-MM-DD | `2026-11-01` |
+| `{PICKUP_TIME}` | HH (24h) | `10` |
+| `{DROPOFF_DATE}` | YYYY-MM-DD | `2026-11-15` |
+| `{DROPOFF_TIME}` | HH (24h) | `10` |
+
+**Worked example — Bangkok airport, Nov 1–15, pickup/dropoff at 10:00:**
+```
+https://www.kayak.com/cars/BKK/2026-11-01-10h/2026-11-15-10h
+```
+
+---
+
+## Step-by-Step Workflow
+
+```bash
+# 1. Ensure browser is running
+pinchtab_ensure || exit 1
+
+# 2. Navigate
+pinchtab nav "https://www.kayak.com/cars/BKK/2026-11-01-10h/2026-11-15-10h"
+
+# 3. Kayak loads results asynchronously — wait longer than usual
+sleep 5
+
+# 4. Extract results
+pinchtab text
+```
+
+If `pinchtab text` returns car listings (provider names, car categories, prices), extract top 5–10.
+
+If results are still loading (spinner text or empty): wait another 3 seconds and retry `pinchtab text` once.
+
+---
+
+## Applying Filters
+
+| Filter | Action |
+|---|---|
+| Car category (economy, SUV, etc.) | Use `pinchtab snap -i -c`, find the category filter tabs at top, click the desired one |
+| Sort by price | Kayak defaults to "Recommended" — find the sort dropdown ref, select "Price: lowest" |
+| Specific provider | Find provider filter checkboxes in the left panel refs |
+
+```bash
+pinchtab snap -i -c
+pinchtab click {sort-ref}
+sleep 2
+pinchtab text
+```
+
+---
+
+## Result Extraction
+
+From `pinchtab text`, look for:
+- Rental provider (e.g. "Hertz", "Avis", "Sixt")
+- Car category (e.g. "Economy", "Compact SUV")
+- Representative car model (e.g. "Toyota Yaris or similar")
+- Daily rate (e.g. "$28/day")
+- Total price for period
+
+---
+
+## Under-25 Driver Note
+
+Most rental providers charge a Young Driver Surcharge for drivers under 25. This cannot be pre-applied via URL on Kayak. Always mention in your reply: *"If any driver is under 25, additional surcharges will apply at the counter — verify with the provider before booking."*
+
+---
+
+## Fallback: Rentalcars.com
+
+Use for locations where Kayak returns no results (city centres, train stations, non-IATA locations).
+
+```
+https://www.rentalcars.com/SearchResults.do?country={COUNTRY_CODE}&pickUpLocName={CITY}&depDate={DD/MM/YYYY}&retDate={DD/MM/YYYY}&depTime=1000&retTime=1000
+```
+
+```bash
+pinchtab nav "https://www.rentalcars.com/SearchResults.do?country=TH&pickUpLocName=Bangkok&depDate=01/11/2026&retDate=15/11/2026&depTime=1000&retTime=1000"
+sleep 5
+pinchtab text
+```
+
+**Note**: Rentalcars.com has a noisier accessibility tree. Use `pinchtab text` exclusively; avoid full snapshot.
+
+---
+
+## Token Efficiency
+
+- `pinchtab text` is sufficient for reading car listings and prices.
+- Use `pinchtab snap -i -c` only for filter/sort interactions.

package/examples/extensions/web-search/skill/references/flights.md

@@ -0,0 +1,133 @@
+# Flights Reference
+
+## Primary site: Google Flights
+
+**Why Google Flights:**
+- Deep-link URL accepts all search parameters (origin, destination, dates, passengers, cabin class, stops) — minimal or zero form interaction needed
+- Clean accessibility tree: price cells have descriptive `aria-label` values (airline, price, duration, stops)
+- No CAPTCHA for read-only searches
+- Authoritative real-time pricing from airlines
+
+**Fallback: Skyscanner** — use if Google Flights is inaccessible or returns no results. URL pattern below.
+
+---
+
+## URL Construction
+
+### Round trip
+
+```
+https://www.google.com/travel/flights#flt={FROM}.{TO}.{DEPART_DATE}*{TO}.{FROM}.{RETURN_DATE};c:{CURRENCY};e:{STOPS};px:{PASSENGERS};t:f;tt:r
+```
+
+| Placeholder | Format | Example |
+|---|---|---|
+| `{FROM}` | IATA airport code | `TLV` |
+| `{TO}` | IATA airport code | `BKK` |
+| `{DEPART_DATE}` | YYYY-MM-DD | `2026-11-01` |
+| `{RETURN_DATE}` | YYYY-MM-DD | `2026-11-22` |
+| `{CURRENCY}` | ISO 4217 | `USD` |
+| `{STOPS}` | `0` = nonstop only, `1` = 1 stop max, `2` = any | `0` |
+| `{PASSENGERS}` | see below | |
+
+**Passenger encoding:**
+- Adults only: `{n}` e.g. `2`
+- With children (use age): `{adults},c{age}` for each child e.g. `2,c7,c3` = 2 adults + child age 7 + child age 3
+- Infants on lap: append `,i{age}` (age 0 or 1)
+
+**Worked example — TLV→BKK, Nov 2026, 2 adults + child 7 + child 3, nonstop, round trip:**
+```
+https://www.google.com/travel/flights#flt=TLV.BKK.2026-11-01*BKK.TLV.2026-11-22;c:USD;e:0;px:2,c7,c3;t:f;tt:r
+```
+
+### One way
+
+Replace `tt:r` with `tt:o` and remove the return leg (`*{TO}.{FROM}.{RETURN_DATE}`):
+```
+https://www.google.com/travel/flights#flt=TLV.BKK.2026-11-01;c:USD;e:0;px:2;t:f;tt:o
+```
+
+### Cabin class
+
+Append `;sc:{CLASS}` where `CLASS` is: `0`=any, `1`=economy, `2`=premium economy, `3`=business, `4`=first.
+Default (omit) shows economy.
+
+---
+
+## Step-by-Step Workflow
+
+```bash
+# 1. Ensure browser is running
+pinchtab_ensure || exit 1
+
+# 2. Navigate to the constructed URL
+pinchtab nav "https://www.google.com/travel/flights#flt=TLV.BKK.2026-11-01*BKK.TLV.2026-11-22;c:USD;e:0;px:2,c7,c3;t:f;tt:r"
+
+# 3. Wait for page to render (Google Flights loads results asynchronously)
+sleep 4
+
+# 4. Extract text — check that flight results are present
+pinchtab text
+```
+
+If `pinchtab text` returns flight results (airline names, prices, durations), extract the top 5–10 and format the reply. Done — no further interaction needed.
+
+If results are not yet loaded (text shows only navigation/header): `sleep 3` and retry `pinchtab text` once.
+
+---
+
+## Filter Interaction (only if not pre-set in URL)
+
+If the user wants a filter that cannot be encoded in the URL (e.g. specific airline preference, baggage included):
+
+```bash
+# Get interactive refs for filter controls
+pinchtab snap -i -c
+
+# Find the relevant filter ref (e.g. "Stops" dropdown, "Airlines" filter)
+# Click it, wait 2 seconds, re-read text
+pinchtab click {ref}
+sleep 2
+pinchtab text
+```
+
+---
+
+## Result Extraction
+
+From `pinchtab text` output, look for lines containing:
+- Airline name (e.g. El Al, Thai Airways, Emirates)
+- Departure and arrival times
+- Duration (e.g. "11 hr 20 min")
+- Stop count (e.g. "Nonstop", "1 stop")
+- Price (e.g. "$1,240")
+
+**Sort order**: Google Flights defaults to "Best" (mix of price + duration). If the user wants cheapest first, look for the sort control and click "Cheapest" via `snap -i -c`.
+
+---
+
+## Fallback: Skyscanner
+
+Use if Google Flights is blocked or returns no results.
+
+```
+https://www.skyscanner.com/transport/flights/{from}/{to}/{YYMMDD_depart}/{YYMMDD_return}/?adults={n}&children={n}&childrensages={age1},{age2}&cabinclass=economy&stops=!oneOrMore&currency=USD
+```
+
+Date format for Skyscanner: `YYMMDD` (e.g. `261101` for 2026-11-01).
+
+```bash
+pinchtab nav "https://www.skyscanner.com/transport/flights/tlv/bkk/261101/261122/?adults=2&children=2&childrensages=7,3&cabinclass=economy&stops=!oneOrMore&currency=USD"
+sleep 5   # Skyscanner loads slower than Google Flights
+pinchtab text
+```
+
+**Known issue**: Skyscanner occasionally shows a cookie consent banner on first load. If `pinchtab text` shows no results, run `pinchtab snap -i -c`, find the "Accept" or "Continue" button ref, click it, then re-navigate.
+
+---
+
+## Token Efficiency
+
+- **Always start with `pinchtab text`** (~800 tokens) — sufficient to read all flight results.
+- Only use `pinchtab snap -i -c` (~3,600 tokens) if you need to click a filter.
+- Never use full `pinchtab snap` for flight searches.