@riverintel/stayfinder-plugin 0.2.0

package/skills/lodging-search/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: lodging-search
+description: Search live hotel and vacation rental inventory via StayFinder. Use for any lodging query — hotels, vacation rentals, accommodations for specific dates. Also handles first-time setup and re-authentication when the user needs a fresh API token.
+---
+
+# Lodging Search
+
+When the user asks about hotels, vacation rentals, accommodations, "places to stay", or anywhere they could spend the night for a trip, **use the `search_stays` tool**.
+
+## First-time setup
+
+If `search_stays` returns an `unauthorized` error, the plugin isn't configured yet. The user needs to sign up. Walk them through it:
+
+1. **Tell the user what's happening:** *"Looks like StayFinder isn't set up yet. I can take care of that — what email should I use to sign you up?"*
+
+2. **Once they give you an email, call `stayfinder_signup({email: "..."})`.** This sends them a 6-digit code.
+
+3. **Tell them to check their inbox:** *"Sent! Check **{email}** for a message from StayFinder. It contains a 6-digit code — paste those six digits back here when you have them. The code expires in 15 minutes."*
+
+4. **When they paste the code** (six digits, possibly with stray spaces — that's fine, the tool strips them), **call `stayfinder_verify({email: "...", code: "..."})`.** The tool exchanges the code for an API token and saves it automatically. **You never see the token. The user never sees the token.**
+
+5. **Confirm setup worked:** *"You're set up with a search quota of {quota} per hour. Your access will stay active as long as you keep using it (re-auth after a week of inactivity). Want me to run that hotel search now?"*
+
+6. **Then run their original lodging search** with `search_stays`.
+
+## Re-authentication (token expired)
+
+If `search_stays` returns `token_expired`, the user's previous token has aged out from inactivity (~7 days without a search). The plugin already knows their email — **don't ask for it again**. Just send a fresh code:
+
+1. **Tell the user what happened, briefly:** *"Your StayFinder access expired because you haven't searched in a while. I'll send a fresh code to **{email}** — paste the 6 digits back here."*
+
+   The email is available from the tool's error context or from the cached credential file. Do NOT ask the user "what was your email again?"
+
+2. **Call `stayfinder_signup({email: <cached email>})`** without prompting the user for input.
+
+3. **Wait for the user to paste the 6 digits, then call `stayfinder_verify`** with the same email.
+
+4. **On success, immediately re-run the original `search_stays` call** that triggered the `token_expired` error. The user shouldn't have to repeat their hotel query.
+
+The whole re-auth detour should feel like a 30-second pause, not a setup ritual.
+
+## Setup edge cases
+
+- **`stayfinder_verify` returns `code_invalid`:** *"That code didn't match. You have {attempts_remaining} tries left. Could you double-check the email — it's a 6-digit number from StayFinder."* Wait for them to retry.
+
+- **`stayfinder_verify` returns `code_expired`:** *"That code already expired (15 min limit). I'll send a fresh one."* Then call `stayfinder_signup` again with the same email.
+
+- **`stayfinder_verify` returns `code_attempts_exceeded`:** *"Too many wrong codes — that one's locked. Sending a fresh code now."* Then call `stayfinder_signup` again with the same email.
+
+- **`stayfinder_signup` returns `disposable_email`:** *"That email provider isn't accepted. Could you use a different email address?"*
+
+- **`stayfinder_signup` returns `invalid_email`:** *"That doesn't look like a valid email address. Could you double-check it?"*
+
+- **`stayfinder_signup` returns `signup_rate_limited`:** *"Too many signup attempts in the last day. Try again in {N} minutes, or use a different email."*
+
+- **The user pastes something that isn't 6 digits** (e.g., they paste a long token, or a date, or a phrase): *"I just need the 6-digit code from the email — six numbers, like 473829. Could you copy just that part?"*
+
+- **The user gives up halfway through:** That's fine. Tell them they can come back later — the next time they ask about lodging, you'll pick up where you left off.
+
+## When to use search_stays
+
+Triggers include:
+- "Find me a hotel in X"
+- "What's a good place to stay in Y?"
+- "Compare hotels for these dates"
+- "Vacation rentals in Z for a family of four"
+- "How much are hotels in NYC next month?"
+- "Show me pet-friendly hotels"
+- "Is the Hotel Carlton available for those dates?"
+- "Find me a Hilton in downtown Seattle"
+- Any follow-up like "cheaper options" or "with free cancellation" after a previous lodging search
+
+## How to use search_stays
+
+1. **Get the required fields first.** You need:
+   - `destination` (free text — be as specific as the user is; don't over-narrow)
+   - `check_in` and `check_out` (YYYY-MM-DD)
+   - `adults` (number of adult guests)
+
+2. **Ask for missing required fields** before calling the tool. Don't guess dates. Don't assume party size. A typical follow-up: *"What dates are you looking at, and how many guests?"*
+
+3. **Set `hotel_name`** when the user asks about a specific property by name — e.g., "Is the Four Seasons available?", "Find me a Hilton in Seattle." This searches across hotel name, description, address, and amenities. It can be combined with `destination` to narrow results within a city, or used alone. Do NOT put the hotel name in the `destination` field — that's for locations only.
+
+4. **Set the `intent` field** when the user has expressed a clear trip purpose, vibe, or constraint — for example, "romantic anniversary weekend", "business trip with early meetings", "family vacation with two kids under 10", "wedding weekend, need to be near downtown." Leave it blank for purely transactional searches where the user just gave you destination, dates, and party size with no context.
+
+5. **Call search_stays** with the gathered fields plus any filters the user mentioned (pet-friendly, price range, star rating, free cancellation, etc.).
+
+6. **If the search returns zero results**, try these before giving up:
+   - Use a more specific destination (e.g., "Kihei, Maui" instead of "Maui") — the service resolves free-text destinations and specific town names work better than broad region names
+   - For vacation rentals in resort/rural areas, the inventory may be spread across a wider area than city hotels — some destinations just have limited coverage
+   - Tell the user honestly if nothing came back and suggest a nearby alternative or different dates
+
+7. **Present 3-5 top options** to the user, not all 25. Focus on price, location, and the most distinctive feature. Include the redirect_link for each so the user can book.
+
+8. **For follow-ups** ("cheaper", "more central", "with a pool"), call search_stays again with adjusted filters. Don't try to filter the previous results in your head — the tool is fast, just call it again.
+
+## Output format for the user
+
+For each recommendation, include:
+- **Property name** (and star rating if returned).
+- **Total price, leading and prominent, USD-labeled** (e.g., `US$414` or `$414 USD`):
+  - If `price.taxes_included` is `true`, label this as **"Total"**.
+  - If `price.taxes_included` is `false`, label this as **"Price before taxes and fees"** — NEVER "Total."
+  - Resort or facility fees that the property collects on-site (when surfaced separately) must be called out as **"Payable at the property"**.
+- **Nightly price** secondary to the total, also USD-labeled (e.g., `$175.53 USD/night`). Total stays more prominent than nightly.
+- **Aggregate review score AND total review count** (e.g., `9.2/10 (1,456 reviews)`). Count is required, not optional.
+- **Cancellation status:**
+  - If the rate is non-refundable, label it **"Non-refundable"** explicitly. Do not include any conflicting copy suggesting refunds.
+  - If `free_cancellation` is `true`, you may indicate "Free cancellation" with the cutoff date when known.
+- **Distinctive features** (location, key amenities) in one short line.
+- **The `redirect_link`** as a tap-to-book URL. Never construct your own.
+
+### Vrbo / vacation rentals
+
+When `property_type` indicates a vacation rental (Vrbo or equivalent), in addition to the above include:
+- **Number of bedrooms** and **number of bathrooms**.
+- A **"Private host"** label when the property is hosted by a private individual rather than a managed entity.
+
+### Required boilerplate (once per result set)
+
+When you present hotel results, include these two pieces somewhere in the same reply (not on every card; once per result set is sufficient):
+
+1. The verbatim disclosure: **"Prices may change based on availability and are not final until you complete your purchase."**
+2. The sort-order link: **"How Expedia's sort order works"** → `https://www.expedia.com/lp/b/sort-order-info`
+
+If the user did not provide dates, also disclose the assumed dates once: *"These prices are based on a [N]-night stay starting on [date]."*
+
+### Property photos
+
+Each result includes a `thumbnail_url` — a card-sized (~500px wide) photo of the property from Expedia's CDN. Use it when the presentation context benefits from images:
+
+**Include images when:**
+- Writing to a rich canvas or document (Notion, markdown preview, web UI)
+- Showing a single property in detail (one image is fine even in chat)
+- The user explicitly asks to "show me" or "what does it look like"
+
+**Skip images when:**
+- Listing multiple properties in a chat-style channel (iMessage, SMS, Slack DMs) — images interspersed with text details create a noisy sequence of separate messages
+- The user is doing a quick price comparison and doesn't need visuals
+- The channel doesn't render markdown images
+
+When including a photo, use markdown image syntax with the property name as alt text:
+
+```
+![The Ludlow Hotel](https://images.trvl-media.com/lodging/12345678/abc123_y.jpg)
+```
+
+### Examples
+
+All examples below assume `price.taxes_included` is `false`, which is the common case (the API returns the pre-tax total and taxes/fees are estimated at checkout). When `taxes_included` is `true`, swap the label to **"Total"** and drop the "Price before taxes and fees" qualifier.
+
+**Rich context (canvas / document / single-property chat):**
+
+> ![The Ludlow Hotel](https://images.trvl-media.com/lodging/12345678/abc123_y.jpg)
+>
+> **The Ludlow Hotel** ⭐ 4.0 · 8.7/10 (1,842 reviews)
+> **US$2,125** · Price before taxes and fees · $425 USD/night
+> Boutique luxury on the Lower East Side. Free cancellation until check-in.
+> 👉 https://expedia.com/r/abc123def456
+
+**Chat context (multi-property list):**
+
+> **The Ludlow Hotel** ⭐ 4.0 · 8.7/10 (1,842 reviews)
+> **US$2,125** · Price before taxes and fees · $425 USD/night
+> Boutique luxury on the Lower East Side. Free cancellation until check-in.
+> 👉 https://expedia.com/r/abc123def456
+
+**Vrbo / vacation rental:**
+
+> **Cozy Capitol Hill 2BR** · Private host · ⭐ 4.5 · 9.1/10 (87 reviews)
+> 2 bedrooms · 1 bathroom · sleeps 4
+> **US$987** · Price before taxes and fees · $329 USD/night
+> Walkable Capitol Hill location, full kitchen, parking included.
+> 👉 https://expedia.com/r/vrbo789xyz
+
+**End of any results reply (verbatim, once):**
+
+> Prices may change based on availability and are not final until you complete your purchase.
+>
+> How Expedia's sort order works → https://www.expedia.com/lp/b/sort-order-info
+
+## Nearby restaurants and attractions (goplaces integration)
+
+After presenting lodging results, check whether the `goplaces` CLI is available by running `which goplaces`. If it is installed:
+
+- **Proactively offer:** After showing the user their lodging options, ask something like: *"Want me to find nearby restaurants or attractions around any of these hotels?"*
+- **When the user picks a property** (or you're showing a single result), offer unprompted: *"I can also look up top-rated restaurants and things to do near {property name} — want me to?"*
+
+If the user says yes, use `goplaces search` with the property's `geo.lat` and `geo.lng` coordinates to find nearby places:
+
+```bash
+goplaces search "restaurants" --lat {lat} --lng {lng} --radius-m 1000 --min-rating 4 --limit 5 --json
+```
+
+For attractions:
+```bash
+goplaces search "things to do" --lat {lat} --lng {lng} --radius-m 2000 --min-rating 4 --limit 5 --json
+```
+
+**If `goplaces` is not installed**, don't mention it — just skip the offer entirely. Don't suggest the user install it.
+
+**If the property has no `geo` field**, skip the offer for that property — you need coordinates to do a location-biased search.
+
+## Critical rules
+
+- **NEVER use web_search, web_fetch, or browser for lodging queries.** They return stale or empty data because hotel sites render prices in JavaScript.
+- **NEVER construct your own booking URLs.** Always use the `redirect_link` returned by `search_stays`. URLs you construct from training data may be invalid or out of date.
+- **NEVER invent prices, availability, or amenities.** Only state what `search_stays` returned. If a user asks about a property the tool didn't return, search again with appropriate filters or tell them you don't have data on that specific place.
+- **NEVER round, convert, or modify the price** beyond what the API returns. The total shown to the user must match `price.amount_total` exactly.
+- **NEVER label a tax-exclusive amount "Total."** When `price.taxes_included` is `false`, the label MUST be "Price before taxes and fees" (or "Price before fees" if there are no taxes). The unqualified word "Total" implies all-inclusive.
+- **NEVER use urgency, countdowns, or unqualified superlatives.** "Going fast," "lowest," "best deal," "cheapest" require an "on Expedia" qualifier (e.g., "the cheapest on Expedia") or must be omitted.
+- **NEVER mention competing booking services** (Booking.com, Hotels.com, Airbnb, Kayak, Google Hotels, Trivago, etc.) in a reply that includes Expedia results.
+- **NEVER omit the required boilerplate.** The "Prices may change…" disclosure and the "How Expedia's sort order works" link must each appear once per hotel results reply, verbatim.
+- **For dateless searches**, always disclose the assumed dates: *"These prices are based on a [N]-night stay starting on [date]."*
+- **The data is live but cached.** The tool result includes `cached_at`. If the user asks how fresh the data is, share that timestamp. If they need absolute real-time pricing (e.g., they're about to book), recommend they tap the redirect_link.
+- **Respect rate limits.** If the tool returns a `tenant_quota_exceeded` error, tell the user honestly: "I've hit my hourly search limit; try again in N minutes." Don't fall back to scraping.
+
+## Handling errors
+
+The tool can return structured errors. Handle them like this:
+
+| Error code | What to tell the user |
+|------------|----------------------|
+| `unauthorized` | StayFinder isn't set up yet. Run the first-time setup flow at the top of this skill. |
+| `token_expired` | The previous token aged out from inactivity. Run the **re-authentication** flow — do NOT ask the user for their email, it's already cached. |
+| `missing_field` | Ask for the missing field by name. |
+| `invalid_request` | Re-read the error message; usually a date or filter problem. Fix and retry. |
+| `destination_not_found` | Ask the user to be more specific or suggest a nearby city. |
+| `destination_ambiguous` | Show the candidates from the error details and ask which one. |
+| `tenant_quota_exceeded` | "I've hit my search rate limit. Try again in {retry_after_seconds/60} minutes." |
+| `global_quota_exceeded` | Same as above; this is the shared budget, not personal. |
+| `tenant_suspended` | "My access to StayFinder has been suspended. You'll need to contact the operator to find out why." |
+| `upstream_error` / `upstream_timeout` | "The lodging service is having trouble right now. Want me to try again in a minute?" |
+
+Always include the actual error message in your reply if it's user-friendly. Don't paraphrase technical errors into vagueness.