Skip to content

skywain/trip-planner-skill

trip-planner

Unverified

End-to-end international trip planning: turns "I want to go to X for N days" into a verified, bookable plan — route skeleton across cities, flight price scans (international + domestic legs), train-vs-fly decisions, hour-by-hour daily timelines with opening hours, dwell times, holiday collisions and tappable turn-by-turn map links (小时级行程+地图导航+离线KML), hotel shortlists by neighborhood, budget rollup, and a booking checklist with deep links. Use this whenever the user asks to plan a trip, vacation, itinerary or honeymoon, compare flight dates/prices, pick between cities or routes, schedule a travel day hour by hour, fill a spare block of time ("I'm near X with 2 free hours"), turn a finished plan into a designed page (eight themed renders: illustrated / clay / noir / glass / journal / zine / splash / portal — 插画/黏土/夜航/玻璃/手账/Zine/闪屏/穿越版), or asks 旅行规划/行程安排/机票比价/去某国玩N天怎么安排/现在有空档干嘛/把行程做成好看的网页 — even if they only mention one piece (just flights, just hotels, or just navigation), the playbook and verification rules here still apply.

FileKindSize
SKILL.mdskill md32.9 KB
assets/plan.example.jsonconfig12.1 KB
examples/README.mdmarkdown13.0 KB
examples/china-2026/china-splash.htmlother937.1 KB
examples/china-2026/china.art.jsonconfig6.4 KB
examples/china-2026/china.geo.jsonconfig58.3 KB
examples/fixtures/bad/bracketed-note.geo.jsonconfig7.8 KB
examples/fixtures/bad/brief-card-not-text.geo.jsonconfig943 B
examples/fixtures/bad/decision-point-date-two-days-before.geo.jsonconfig848 B
examples/fixtures/bad/decision-point-day-date-not-iso.geo.jsonconfig7.8 KB
examples/fixtures/bad/decision-point-no-if-no.geo.jsonconfig715 B
examples/fixtures/bad/decision-point-same-what.geo.jsonconfig8.2 KB
examples/fixtures/bad/decision-point-src-not-http.geo.jsonconfig803 B
examples/fixtures/bad/decision-point-t-not-hhmm.geo.jsonconfig764 B
examples/fixtures/bad/decision-points-null.geo.jsonconfig594 B
examples/fixtures/bad/driver-enum.geo.jsonconfig711 B
examples/fixtures/bad/driver-self-no-driving-card.geo.jsonconfig736 B
examples/fixtures/bad/driving-card-no-as-of.geo.jsonconfig861 B
examples/fixtures/bad/driving-card-no-desk.geo.jsonconfig800 B
examples/fixtures/bad/driving-card-no-legality-line.geo.jsonconfig811 B
examples/fixtures/bad/driving-card-no-verdict.geo.jsonconfig939 B
examples/fixtures/bad/driving-card-zh-verdict-trailing.geo.jsonconfig967 B
examples/fixtures/bad/hotel-checkout-null.geo.jsonconfig786 B
examples/fixtures/bad/hours-as-of-not-date.geo.jsonconfig674 B
examples/fixtures/bad/hours-bare-string.geo.jsonconfig655 B
examples/fixtures/bad/hours-src-not-http.geo.jsonconfig662 B
examples/fixtures/bad/hours-text-empty.geo.jsonconfig647 B
examples/fixtures/bad/kind-enum.geo.jsonconfig7.9 KB
examples/fixtures/bad/must-false.geo.jsonconfig914 B
examples/fixtures/bad/must-no-stand.geo.jsonconfig755 B
examples/fixtures/bad/must-no-view.geo.jsonconfig758 B
examples/fixtures/bad/must-not-boolean.geo.jsonconfig798 B
examples/fixtures/bad/must-see-unmatched.geo.jsonconfig963 B
examples/fixtures/bad/must-see-view-empty.geo.jsonconfig910 B
examples/fixtures/bad/pending-no-checklist-row.geo.jsonconfig1021 B
examples/fixtures/bad/refundable-not-boolean.geo.jsonconfig686 B
examples/fixtures/bad/rental-leg-no-driving-card.geo.jsonconfig829 B
examples/fixtures/bad/review-counts-disagree.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-lens-enum.geo.jsonconfig1.1 KB
examples/fixtures/bad/review-no-driving-lens.geo.jsonconfig1.3 KB
examples/fixtures/bad/review-not-object.geo.jsonconfig611 B
examples/fixtures/bad/review-single-pass-with-counts.geo.jsonconfig1.0 KB
examples/fixtures/bad/review-two-lenses.geo.jsonconfig959 B
examples/fixtures/bad/self-drive-no-driving-card.geo.jsonconfig635 B
examples/fixtures/bad/sub-stop-no-name.geo.jsonconfig763 B
examples/fixtures/bad/sub-stop-no-query.geo.jsonconfig763 B
examples/fixtures/bad/sub-stops-null.geo.jsonconfig578 B
examples/fixtures/bad/tour-confirmed-prefix.geo.jsonconfig902 B
examples/fixtures/bad/tour-not-boolean.geo.jsonconfig562 B
examples/fixtures/bad/tour-on-day-object.geo.jsonconfig7.8 KB
examples/fixtures/bad/tour-unconfirmed.geo.jsonconfig837 B
examples/fixtures/strict/clean.plan.geo.jsonconfig4.5 KB
examples/fixtures/strict/hours-as-of-after-asof.geo.jsonconfig4.1 KB
examples/fixtures/strict/hours-missing-in-window.geo.jsonconfig4.0 KB
examples/fixtures/strict/hours-stale-as-of.geo.jsonconfig4.1 KB
examples/fixtures/strict/no-generated.geo.jsonconfig3.8 KB
examples/fixtures/strict/refundable-no-clause.geo.jsonconfig3.8 KB
examples/fixtures/strict/rows-without-clock-or-kind.geo.jsonconfig3.7 KB
examples/fixtures/strict/self-drive-not-legal-no-decision.geo.jsonconfig4.4 KB
examples/fixtures/strict/t-n-date-mismatch.geo.jsonconfig3.8 KB
examples/fixtures/strict/tour-no-review.geo.jsonconfig3.4 KB
examples/fixtures/substops.plan.geo.jsonconfig9.1 KB
examples/gates-sample.icsother11.5 KB
examples/japan-2026/japan-illustrated.htmlother1.4 MB
examples/japan-2026/japan.art.jsonconfig6.2 KB
examples/japan-2026/japan.geo.jsonconfig65.5 KB
examples/kyoto-sample.htmlother13.0 KB
examples/kyoto-sample.kmlother1012 B
examples/kyoto-sample.plan.geo.jsonconfig7.2 KB
examples/mexico-2026/mexico-journal.htmlother2.0 MB
examples/mexico-2026/mexico.art.jsonconfig9.4 KB
examples/mexico-2026/mexico.geo.jsonconfig77.1 KB
examples/morocco-2026/morocco-glass.htmlother1.3 MB
examples/morocco-2026/morocco-portal.htmlother13.8 KB
examples/morocco-2026/morocco.art.jsonconfig3.8 KB
examples/morocco-2026/morocco.geo.jsonconfig85.1 KB
examples/nordic-2026/nordic-noir.htmlother686.8 KB
examples/nordic-2026/nordic.art.jsonconfig8.7 KB
examples/nordic-2026/nordic.geo.jsonconfig58.5 KB
examples/turkey-2026/turkey-clay.htmlother1.3 MB
examples/turkey-2026/turkey.art.jsonconfig3.5 KB
examples/turkey-2026/turkey.geo.jsonconfig75.8 KB
examples/vietnam-2026/vietnam-zine.htmlother2.5 MB
examples/vietnam-2026/vietnam.art.jsonconfig10.8 KB
examples/vietnam-2026/vietnam.geo.jsonconfig85.1 KB
references/art-schema.mdmarkdown318 B
references/country-quick-notes.mdmarkdown58.6 KB
references/cover-titles.mdmarkdown10.6 KB
references/data-sources.mdmarkdown49.2 KB
references/navigation.mdmarkdown23.6 KB
references/output-template.mdmarkdown49.2 KB
references/phase-0-intake.mdmarkdown12.4 KB
references/phase-1-brief.mdmarkdown22.8 KB
references/phase-3-legs.mdmarkdown10.5 KB
references/phase-4-days.mdmarkdown13.6 KB
references/phase-6-assemble.mdmarkdown22.3 KB
references/scheduling.mdmarkdown28.8 KB
references/themes.mdmarkdown37.9 KB
scripts/build_site.pyscript47.8 KB
scripts/flight_scan.pyscript18.9 KB
scripts/plan_lint.pyscript58.4 KB
scripts/render_plan.pyscript28.2 KB
scripts/route_tools.pyscript90.0 KB

references/data-sources.md

View on GitHub
# Data sources & URL recipes

Fallback order everywhere: bundled script / keyless API → browser pane → web search →
deep link marked "verify on click". Statuses marked ✓ were live-tested 2026-08-01.

## Flights
- **scripts/flight_scan.py** (Google Flights via fast-flights, no key). One-time
  dependency: `python3 -m pip install --user fast-flights`. A Homebrew / Debian Python
  refuses that with `externally-managed-environment` (PEP 668) — then run
  `python3 -m pip install --user --break-system-packages fast-flights`, or make a venv
  (`python3 -m venv ~/.trip-venv && ~/.trip-venv/bin/pip install fast-flights`) and run
  the script with `~/.trip-venv/bin/python3`. The script prints these lines and a
  browser link when the import fails, so a missing dependency never blocks a plan —
  and "cannot install" is not a reason to price from a web search: the next rung is
  the browser (SKILL.md §When things fail; §Second price source below); only a harness
  with no browser pane drops to the web-search rung, and `legs.note` then says
  "single source — no browser".
  `python3 scripts/flight_scan.py --from PVG --to NRT --depart 2026-10-01 --nights 10-15 --flex 2 --max-fetches 30`
  That grid is 5 dates × 6 trip lengths = 30 combos against a default cap of 12, so
  either pass `--max-fetches` as shown (~5-10 s per combo) or let it scan centre-out
  around your requested date — truncation drops the edges of the grid, never the date
  you actually asked about. One-way (for open-jaw halves): add `--oneway` and drop
  `--nights`. Prices are Google's cache — comparison grade; the deep link printed with
  each row is the source of truth. It sleeps between fetches and retries once on the
  transient throttling Google does to repeat callers.
  **Cheapest-by-price hides usable flights**: the low rows are red-eyes and next-day
  arrivals. For any leg feeding a pinned event or a tour pickup window, scan with
  `--arr-before HH:MM` (and `--dep-after`) — "cheapest USABLE flight" is the number
  the plan needs (live case: CMH→SLC sticker floor $132 was an overnight horror;
  the usable floor was $207).
  **Read the head line of the output first**: it states the **currency** and whether
  each price is **per person or the total** for `--adults N` — it is the **TOTAL for
  all passengers** (`--adults 2` doubles the number; divide by N for per-person) and
  the budget table copies that wording; `--currency XXX` sets the reported currency
  (default follows the Google region). Two testers had to mark their whole budget
  "⚠ pp or total unknown" before this line existed. `--nonstop` keeps only nonstop options — the LHR→HND
  test saw nothing but 30-40 h two-stop rows in the cache until it was asked for
  nonstops; for a long-haul leg run both with and without and quote both floors.
  An **`AssertionError`** means Google returned a non-200 page (bot wall / consent
  page) and the fallback renderer failed too — the error line echoes route + date
  only so you can see which grid cell died; it is **not** a bad airport code
  (CNS→PEK failed on three valid dates this way). Wait and retry, then open Google
  Flights in the browser and the second price source below; "price unverified" only
  when every source fails. The scan
  returns **outbound legs only** for a return trip: the return leg's departure time
  is not in the output — read it off the deep link when the plan needs a clock.
- **Browser**: `https://www.google.com/travel/flights?q=` + URL-encoded natural
  language, e.g. `Flights from PVG to KIX on 2026-10-02 returning from NRT 2026-10-14
  for 2 adults` — the q= parser understands open-jaw phrasing. Currency follows the
  Google region.
- **Second price source — the rule, then the recipes.** Every international leg's
  pick and backup must appear in **≥ 2 sources** (or be re-checked once on the
  carrier's own site) — the one exception is a harness with no browser pane, where
  Google alone ships and `legs.note` says "single source — no browser";
  `legs.note` names the sources with the as-of date ("sources: Google +
  Skyscanner, 2026-08-15"). When the sources disagree by more than 10 %, the `price`
  field carries the band, not one number ("¥6,900–7,600"). Google failing is a reason
  to open the next source, not a reason to write "price unverified".
  - Skyscanner (site URL, no partner id; parameter names checked 2026-09):
    `https://www.skyscanner.net/transport/flights/{orig}/{dest}/{YYMMDD}/{YYMMDD}/?adultsv2={N}&cabinclass=economy&rtn=1&preferdirects=false&currency={HOME}&locale={en-GB|zh-CN}`
    — one-way: drop the second date and set `rtn=0`; multi-city ⚡ (verify on first
    use, no `rtn`):
    `/transport/flights-multi-city/{o1}/{d1}/{YYMMDD}/{o2}/{d2}/{YYMMDD}/?adultsv2={N}`.
    Carries OTA and LCC inventory Google's cache
    misses, and a month view for flexible dates. Browser pane only (bot wall on curl).
  - Kayak: `https://www.kayak.com/flights/{ORIG}-{DEST}/{YYYY-MM-DD}/{YYYY-MM-DD}/{N}adults?sort=bestflight_a`
    ⚡ verify the first time it is used in a session.
  - ITA Matrix (`matrix.itasoftware.com` — fare rules, booking classes, open-jaw
    pricing; it cannot sell a ticket): read the rules there, then price on Google or
    the carrier's site.
  - Mainland-China networks reach neither Google nor Skyscanner: there the Trip.com
    line below is the primary source and Google the backup.
- **CN networks / CN carriers**: https://www.trip.com/flights/ (or flights.ctrip.com)
  in the browser pane. Also check one LCC direct (Spring 春秋, Peach, Scoot, AirAsia…).
- **Never** curl airline/OTA sites — instant bot-block, wasted call.
- **Carrier rules and clocks move after booking ⚡**: check-in and bag-drop cutoffs
  (live case: a regional carrier lengthened its cutoff mid-season), the
  check-in terminal or lobby, and seasonal timetables (IATA seasons switch on the last
  Sunday of March and of October; a booked departure can move by tens of minutes).
  Source = the carrier's own travel-alerts page and the booking itself, not the
  original confirmation email. When to re-read them on the road: output-template.md
  §On-trip re-audit rows.

## Group tours (跟团) — when the traveller prefers not to self-drive
The tour product replaces flights+car+hotel for its days, so research it FIRST — its
schedule dictates the surrounding legs, not the other way around.
- **Where to look**: operator sites first (prices/terms authoritative), then
  aggregators (Viator = often the only statically readable price; GetYourGuide;
  TakeTours), and Chinese-language operators (走四方 usitrip / 途风 Tours4fun / 悦禾
  joytrav) — often cheaper, pages usually JS-only.
- **The departure-day schedule (班期) is life-or-death**: multi-day tours run fixed
  weekdays, and the product you want may simply not exist (learned live: no 2-day
  Yellowstone tour departs SLC at all — shortest is 3-day, and only a "Day 1 =
  airport-pickup day" 4-day structure preserved the onward flight). JS booking
  calendars cannot be verified statically: with the browser pane, verify — page the
  pricing calendar and read each date cell (bookable / sold-out / blank); no browser
  → ship the calendar link + mark the departure days unverified, never guess them.
  **The listing's "Available Days: Mon, Tue…" line is marketing, not schedule**:
  checked live against five product calendars, it contradicted every one of them.
- **Fly-in day tours live on a weekday grid with two axes**: the operator's real
  departure days AND the feeder flights' weekday schedule — feasibility is the
  AND of both (learned live: a Sunday Oahu→Big Island day trip was structurally
  dead — no inter-island flight before 8:00 on Sundays AND no package departing
  Sundays; Monday had three pre-7:00 flights, $26 cheaper). When the AND fails,
  don't force it: swap two adjacent flexible days so the fly-in lands on a
  workable weekday — and swap BEFORE anything in the pair is ticketed.
- **Min-party lines bite solo travellers**: drive-yourself products (UTV, buggy)
  often require "minimum 2 participants" per booking — no pairing with
  strangers; operators usually sell a ride-along/passenger variant that books
  solo, so ask. Operator chatbots hedge ("may not be available…"): the booking
  calendar is the answer, not the bot.
- **Price anatomy** (quote ALL of it, not the sticker): double-occupancy base;
  single supplement ×1.3-1.6 or listed at checkout; mandatory fee package
  (门票包, $90-140 on US park tours); **non-resident surcharges** (US parks:
  +$100/person at 11 flagship parks from 2026 — ask who collects it;
  country-quick-notes.md §USA); driver-guide tips $10-15/person/day (often cash).
- **Structure quirks to check**: which day is a pickup/dropoff day (not a touring
  day); what time it returns on the last day (operators state "book flights after
  X:00" — obey it); overnight-bag-only luggage rules on 2-day tours; the product's
  stated guide or audio language against `prefs.languages` (none matches → say so on
  the row: it has no commentary advantage; price one that does beside it when one
  exists — an own-language operator, an audio guide); whether the advertised sight is a stop or a drive-by, and for a view, **which of the must-see pictures**
  the stop reaches (phase-4-days.md step 2). Group tours stop only where the whole
  group can go: a viewpoint that needs a 30-60 min walk (an overlook trail, a long stair) is
  usually skipped even when the product says it visits the sight ("boardwalks",
  "see X"), and a multi-day tour rarely backtracks for a skipped stop — the next day
  runs another part of the route. When a must-see picture is taken from such a spot: ask in
  writing before booking, pick a product that names that spot, or price that day
  self-driven once `brief.driving` covers that jurisdiction and driver
  (phase-1-brief.md §Driving card; phase-3-legs.md §Driving legs).
- **Audit the finalists like a hostile lawyer** (1-2 shortlisted products, not the
  longlist): the date-specific fare beats the "From $X" banner (select the date,
  read the fare row — live case: $229 banner, $239 on every bookable date); "park
  entrance fees included for US Residents with acceptable ID" means NOT included
  for your traveller; pickup-point lists often render only inside checkout — walk
  to the checkout page without paying to read them; put the operator phone from
  the product page on the checklist row (the recurring 1★ failure mode is a missed
  pickup with an unreachable driver). If pickup is confirmed "by phone the night
  before" (US operators routinely do this), the plan's connectivity brief must
  require a **local-voice-capable** SIM — data-only eSIMs can't take the call.
- **The OTA's pickup-location field is not the operator's manifest**: where a
  product uses a pickup-list picker (seen on GetYourGuide; other OTAs likely
  match), the field persists only entries from the operator's predefined
  list; when the hotel isn't on it,
  the "drop a pin on the map + add a note" fallback can report "processed"
  yet read back empty after a refresh, and nothing reaches the driver's sheet
  (live case: a Jackson hotel missing from a GetYourGuide pickup list; two
  bookings silently kept an empty pickup field). The reliable channel is
  written, not the UI, and **the user sends it** (SKILL.md Hard rule 1: the
  agent never enters personal data anywhere — a hotel address plus booking
  reference through a live booking is exactly that): the plan drafts **one
  message** and ships it as a checklist row — the user sends it through the
  booking right after booking, because operators otherwise ask in batches, one
  round-trip each. It carries: pickup lodging + full street address + booking
  reference; the **must-stop viewpoints, stated as needs, not as a route** (what
  it is, why it matters, what the traveller accepts — an extra fee, a later
  return, walking it alone while the group does something else); meal choices and
  dietary needs; on US park tours, non-resident park-pass holders
  (country-quick-notes.md §USA); a
  reachable local voice number. A second deadline row, "written confirmation
  received (pickup + must-stop viewpoints)", closes it; the reply fills each must
  sub-stop's `confirmed` (output-template.md §city-block). A written "no" before
  the tour still leaves time to switch product, day or mode; asking the guide on
  the day depends on goodwill. The empty pickup field is harmless once the
  operator's reply exists. Operator silent for ~3 days — or half the time
  remaining to pickup, whichever is shorter — the row escalates: the user
  quotes the booking reference in the OTA's support chat.
- **Reserve-now-pay-later + free cancellation = zero-cost options**: when a
  decision gate (a squad announcement, a companion's dates, an unresolved branch)
  blocks commitment and the departure is capacity-limited ("Likely to sell out"),
  the checklist's TOP row becomes "place the free hold on the branch-compatible
  date now" with the free-cancel deadline as its own row — the user places it
  (SKILL.md Hard rule 1: the agent never books or holds anything). The hold costs nothing,
  survives the gate, and turns "wait and hope" into "decide at leisure". The
  same logic orders ALL bookings: free-cancel holds first, refundables next,
  non-refundables last — every ticketed non-refundable freezes the re-planning
  around it (a pair of "freely swappable" days stops being free the moment the
  flights inside it are ticketed). The rule's converse prices the refund premium:
  refundability is worth paying for while a live gate can still move that date;
  once a night sits wedged between already-ticketed non-refundables with no open
  gate touching it, the premium buys almost nothing — the scenarios that would
  cancel it are trip-collapse ones, which belong to travel insurance
  (trip-cancellation/interruption cover — provided the policy predates the
  hazard's announcement; §Travel insurance "buy before the world moves"), not
  to per-booking refund fees.

## Hotels
No good keyless API exists — use browser + deep links; recommend neighborhoods and
2-3 properties with a price band, and let the user's click show live prices.
- **Compare on the checkout screen's all-in total, never the list price**:
  resort/amenity/urban fees ($30-56/night on resort strips, common in NYC) plus
  ~19% taxes sit between the two — sometimes inside the list price, sometimes
  payable at the property; only the final screen settles which. Calibrate scores
  to the destination's baseline (an ageing resort strip's 8.0 ≈ a mainland
  boutique's 8.5), and when the itinerary has pre-dawn starts, read the RECENT
  low reviews for the three sleep-killers — AC, street/door noise, slow
  elevators — before price breaks the tie. **Cross-validate the score on a second
  platform with a different reviewer base** (Booking ↔ Agoda; Google as
  tie-break): the bases weight cleanliness, noise and breakfast differently, so
  agreement adds confidence and a gap >0.5 is itself a finding — read that
  hotel's low reviews before shortlisting it. The cross-check applies to PRICE
  too: platforms contract different rates for the same room (Agoda often
  undercuts for Asia-market users by tens of dollars a night) — compare
  like-for-like (same room, refundable vs non-refundable) before paying, and
  remember the cancellation terms you get are the booking platform's, not the
  cheapest platform's.
- Google Hotels (browser): https://www.google.com/travel/hotels — search the city,
  **set the dates in the page UI and confirm they display before reading prices**:
  URL date parameters are silently ignored, and the default view shows near-term
  base rates that look plausible (caught live — the first read was August prices
  wearing a September URL).
- Booking deep link with dates baked in:
  `https://www.booking.com/searchresults.html?ss={CITY}&checkin={YYYY-MM-DD}&checkout={YYYY-MM-DD}&group_adults={N}&order=review_score_and_price`
- Agoda often beats Booking in Asia — search in browser, copy property links.

## Travel insurance (旅行险)

- **Three layers, and the numbers live in the last one**: the product page's
  coverage table sells, the clause PDFs define, and the issued policy schedule
  (保单) decides — on the audited product, clause after clause read
  "以保险单载明为准" for exactly the numbers that matter (illness waiting
  period, deductible and payout ratio, delay-hour thresholds, per-category
  sub-limits). Verification does not end at the purchase screen: the picker
  lookalikes and the waiting-period question bite BEFORE buying; the rest is
  read off the issued policy (the user supplies it). Four checks — the
  destination list (the purchase flow's picker, on the user's side, has
  lookalikes of its own: "United States Minor Outlying Islands" is NOT Hawaii
  — Hawaii lives under "United States"), the illness waiting period (a 15-day
  trip dies on a 30-day wait), deductible/payout ratio, and the assistance
  hotline, which may appear nowhere else (live case: the clause docs named no
  provider at all; the hotline existed only on the schedule).
- **Buy before the world moves**: trip-change/cancellation cover excludes events
  already announced or occurred at purchase time (declared strikes, named
  storms, an erupting volcano, announced epidemics). When the plan carries a
  monitored natural-hazard gate, the insurance row's deadline is NOW, not
  "before departure" (the user buys — SKILL.md Hard rule 1) — every day of
  delay is a day the exclusion can crystallise.
- **Match the itinerary's activities against the exclusion list by name**: main
  policies exclude a defined high-risk-sports list — horse riding/马术 commonly
  sits on it (it did here), alongside diving and climbing; the fix is a product
  whose high-risk extension names the activity — and the extension's claim
  rules bind (live case): the operator booking voucher plus an incident
  certificate FROM THE ORGANISER were required claim documents, so the plan's
  day note says to keep them. Guided sessions inside a licensed commercial
  venue usually satisfy the organised-activity carve-out; the same activity
  self-organised often does not.
- **Riders can carry purchase-time windows**: an event-ticket cancellation rider
  demanded insuring within a day of paying for the ticket — tickets bought
  before the policy can never be covered by it, and a ticket bought at a later
  gate needs the same-day insurance linkage written on that gate's checklist
  row. Read which clause actually carries each prepaid item's risk: a delay
  rider quietly covered missed-event ticket loss the cancellation rider could
  not.
- **A self-drive day is a stack, and travel insurance is the thin layer**: the
  personal-liability rider excludes motor vehicles wholesale, and on the
  audited policy the rental-car rider was a gap-filler paying only on top of
  the rental counter's own CDW/theft/third-party cover — declining the
  counter's coverage leaves the rider paying nothing (check whether the user's
  policy is excess-only or primary). Say it on the self-drive day itself:
  third-party cover comes
  from the rental counter, not the travel policy; and watch the policy's
  blood-alcohol line (20 mg/100 mL ≈ one drink on the audited policy — it
  voids the whole day, not just the drive).
- **Once bought, the 保险 brief becomes an operating card, not a purchase
  reminder**: assistance hotline + policy number, the first-call rule
  (approval-first clauses are common — on the audited policy, medical
  transport arranged without the assistance company's approval was not
  reimbursed), and the evidence discipline — hospital ER over standalone
  clinics (the medical-facility definition can exclude urgent-care
  storefronts), itemized bill before leaving, police report within the
  policy's window (24 h here) for theft, PIR at the baggage belt, and
  jewellery is often an excluded or sub-limited property class, so advise
  leaving it home.

## Car rental
Legality comes first and is not a rental question: whether the destination's law
recognises the licence is the `brief.driving` card (phase-1-brief.md §Driving card;
country facts in country-quick-notes.md, "Destination not listed?" driving line and §USA
Driving) — price nothing until it passes. The booking tactics (pay at the counter,
late return, add-ons to skip, car class) are phase-3-legs.md §Driving legs; this section
is where the numbers come from.
- **Three price surfaces, same car class** ⚡: an aggregator in the browser pane for
  the spread; the brand's site for the pickup country; the same brand's site for the
  renter's **home market** (country selector or home-market partner), which often
  sells an inclusive rate the destination site sells as base + counter add-ons.
  Read each on the final screen, pay-at-counter rate where offered, all-in: base +
  taxes and airport fees + one-way fee + the cover lines below.
- **What "inclusive" must contain before it compares**: a collision / loss damage
  waiver (CDW/LDW) and third-party liability, with the excess amount — the layer the
  travel policy's rental rider sits on top of (§Travel insurance, "a self-drive day is
  a stack"). A rate missing either is priced plus the counter's version.
- **The desk's licence terms** are read on the brand's own page for the pickup
  country, dated, and the branch's written answer goes into `brief.driving`.
  The user books (SKILL.md Hard rule 1).

## Intercity rail / bus / local transit
- Durations & connections (browser, keyless):
  `https://www.google.com/maps/dir/?api=1&origin={A}&destination={B}&travelmode=transit`
  (mainland China: this recipe is fine *for you, the planner, on the browser pane*,
  but never ship a Google link to the traveller there — see navigation.md provider
  note).
- Mode overview A→B: `https://www.rome2rio.com/map/{A}/{B}` (browser).
- SE Asia bookings: `https://12go.asia/en/travel/{a}/{b}`.
- Rail: price on the operator's site (country-quick-notes.md lists them). Resellers
  (Omio/Trainline/Klook) are acceptable when operator sites reject foreign cards —
  note the markup in the plan.
- China domestic: 12306 via browser only (12306.cn/en, passport-registered account,
  foreign Visa/Mastercard accepted ⚡; sales open 15 days ahead in station batches);
  Trip.com resells with a fee when the card fails. Real-name rules, the four
  pre-sale clocks and station security are in country-quick-notes.md → China
  (inbound).

## Geocoding & day-route sanity — ✓
Venue-level coordinates come from Nominatim/OSM via `scripts/route_tools.py geocode` —
keyless; the script enforces the usage policy (User-Agent + 1 req/s throttle + cache),
so never call Nominatim in parallel or outside the script. Misses: pull coordinates
from the Google Maps place card in the browser and fill them into the plan JSON by
hand. **Nominatim is weak on non-Latin place names** (Japanese, Chinese, Korean,
Thai…) and fails *quietly* — a station or lane resolves to a similarly named place
a few hundred metres away; the script WARNs when the resolved `display_name` does
not contain the query's head token (first Latin word of ≥4 letters, or the first 2
CJK characters). For those countries pre-filling `est`
coordinates for everything known is the normal path (a trip with 0 Nominatim
requests is fine). Then `check` (distance/clustering sanity), `links` (per-hop +
whole-day deep links — **`--provider google|apple|amap`**, default Google; `amap`
or `apple` for mainland China where Google links are dead, `amap` emits per-hop
links only with no day chain), `kml` (offline pins for Organic Maps / My Maps —
the provider-independent fallback), `sun` (civil dawn / sunrise / sunset per day,
written as `天亮 HH:MM · ☀ HH:MM / 🌇 HH:MM · TZ · sunrise-sunset.org`, or with the
dawn word `dawn …` when the plan is `en` — `--lang zh|en` > `plan.lang` >
`plan.meta.lang` > zh; renderers accept both).
Details: references/navigation.md.
- `check` reads a per-stop `mode` from the vocabulary **`walk | transit | fly |
  drive | boat | train | bus`** (the hop *into* that stop). Anything undeclared is
  guessed from distance, and a guess is silent: a 1.7 km coastal walk becomes
  "transit" and the day's on-foot total reads 0 — declare signature walks. Declared
  fly/drive/boat/train/bus hops are listed as long hops, not `SUSPICIOUS`, so a
  plan with a flight or a reef boat can pass `check` cleanly.
- `check`'s transit durations are a distance formula with no knowledge of tunnels,
  express lines or airport trains: **for any transit hop >20 km it says "use the
  operator timetable" — do that** (Flytoget OSL→Oslo S is 19 min; the formula gave
  195-285). Timetable = operator site (country-quick-notes.md lists them) or the
  Google Maps transit deep link above at the hour the plan uses it.

## Traveller consensus — how people actually do it
Where travellers who share the user's language post about a destination: evidence for
the trip's shape (self-drive or tour, which base, which viewpoint is the point, what
disappointed), never for prices, hours or rules. When to read it, the one
`decisions[]` row and showing a disagreement to the user: phase-1-brief.md §Where the
facts come from; for tour vs drive, phase-3-legs.md §Driving legs. Sources ⚡:
- Mainland-Chinese travellers: Xiaohongshu 小红书, Mafengwo 马蜂窝, Qyer 穷游 —
  search `{destination} 自驾` / `跟团` / `攻略`.
- Korean: Naver blogs and cafés. Japanese: 4travel, note.com. English: Reddit
  r/{destination} and the Tripadvisor destination forum.
- Login wall or app-only → the browser pane; still walled → write "community
  consensus not checked". Never log in for the user, never fill it from memory.

## Venues, tours, tickets
- Hours/closures: official venue site first; Google Maps place card second (watch for
  "Temporarily closed"); blogs last and only if <12 months old.
- Ticket platforms for comparison + booking links:
  Klook `https://www.klook.com/search/?query={q}` ·
  GetYourGuide `https://www.getyourguide.com/s/?q={q}` · KKday · Viator.
  Platforms sometimes cost MORE than the official site — compare before recommending.
- **Event tickets (sports, concerts) ⚡**: team or venue site → the primary seller →
  resale marketplaces (StubHub, SeatGeek, Vivid Seats…); compare resale on the
  **checkout all-in** — the fees appear only on the last screen. A primary seller's
  fraud screen can reject the mix foreign card + VPN + brand-new account with a
  generic error: the user retries from a home network without the VPN, or buys
  resale. A declined attempt can leave a **pending authorisation — not a charge**; it
  drops off. Resale tickets usually land in an account on the primary platform as a
  **mobile-only rotating code**: the user creates that account and installs its app
  before the trip (checklist row). The user buys (SKILL.md Hard rule 1).
- **Timed entry — read the remaining slots before choosing a release window**:
  recreation.gov ticket facilities (US federal sites; the page URL is
  `/ticket/facility/{id}`) answer
  `curl -s -A "Mozilla/5.0" "https://www.recreation.gov/api/ticket/availability/facility/{id}?date={YYYY-MM-DD}"`
  (undocumented; answered live 2026-10-02 ⚡ — fields may change): one row per
  `tour_time`, with `inventory_count` and `reservation_count` per sale channel and
  `booking_windows` (`PRIMARY` / `SECONDARY` release windows, each with its open and
  close instant); `[]` =
  wrong id or nothing that date. Vehicle timed-entry products (`/timed-entry/{id}`)
  use another endpoint, not checked. An advance window that still has seats beats
  sending the user to gamble on a next-day release; a sold-out slot's release instant
  becomes a checklist gate.

## Public holidays — ✓
`curl -s "https://date.nager.at/api/v3/PublicHolidays/{year}/{ISO2}"` (keyless,
instant). Long weekends near the trip = domestic-tourist crowds even without a direct
collision — check the adjacent weeks too.
**It lists fixed-date secular / statutory holidays only.** In Muslim-majority
countries the lunar-calendar holidays — Eid al-Fitr, Eid al-Adha, Mawlid, Islamic New
Year, and Ramadan itself — are **absent** (2026/MA returned 10 rows, every one a
fixed civic date, zero Eids); Buddhist-calendar holidays in Thailand, Laos, Myanmar,
Sri Lanka (Vesak, Asalha Puja, Khao Phansa…) and the Lunar New Year cluster across
East/Southeast Asia are patchy or missing the same way. Spend one budgeted search on
them: the country's official gazette / government holiday page, or a religious-
holiday calendar page (timeanddate-style) for the year — and put the dates in
`brief.holidays` with that source. Eid dates are moon-dependent and published as
"expected" until ~1 day before: mark them ± 1 day.

## Weather — ✓ (archive call can take ~10 s on first hit)
1. Geocode the city: `curl -s "https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1"`
2. **Normals for dates beyond the forecast window — two calls, never one year's
   sample.** Last year's same dates is one draw (one typhoon week rewrites "October
   in Tokyo"); use both of these and write what they agree on:
   - 2a. Five-year archive window, one call per city (✓ 2026-09-02: the call spans the
     whole {dates-5y}→{dates-1y} range — 1,471 daily rows for a 10-day trip, of which
     only the rows whose month-day falls inside the trip's dates are used;
     on 2026-09-03 the endpoint answered 502 to every
     window for an hour — transient: retry with `--max-time 90`, and fall back to 2b
     alone if it stays down; the three extra variables ⚡ re-verify on first use):
     `curl -s --max-time 90 "https://archive-api.open-meteo.com/v1/archive?latitude={lat}&longitude={lon}&start_date={dates-5y}&end_date={dates-1y}&daily=temperature_2m_max,temperature_2m_min,apparent_temperature_max,precipitation_sum,precipitation_hours,wind_gusts_10m_max&timezone=auto"`
     Keep only the rows whose month-day lies inside the trip window (5 per date),
     then aggregate per month-day: median max / min, the share of
     rain days (≥ 1 mm), the wettest day, the gustiest day.
   - 2b. Climate-model normals, three models averaged (✓ 2026-09-03, keyless, any
     future date):
     `curl -s --max-time 90 "https://climate-api.open-meteo.com/v1/climate?latitude={lat}&longitude={lon}&start_date={dates}&end_date={dates}&models=EC_Earth3P_HR,MRI_AGCM3_2_S,MPI_ESM1_2_XR&daily=temperature_2m_max,temperature_2m_min,precipitation_sum"`
     The response carries one column per model (`temperature_2m_max_EC_Earth3P_HR` …):
     **average them and never quote a single model** — two models put 5 mm and 70 mm
     on the same day in testing.
3. Trip dates within 16 days of today → the real forecast for those dates (✓
   2026-09-03 with every variable below):
   `curl -s --max-time 90 "https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&daily=temperature_2m_max,temperature_2m_min,apparent_temperature_max,precipitation_probability_max,uv_index_max,wind_gusts_10m_max&timezone=auto&forecast_days=16"`
   `apparent_temperature_max` + `uv_index_max` (heat), `wind_gusts_10m_max` (wind),
   `precipitation_probability_max` (rain) and `temperature_2m_min` (cold) are what
   scheduling.md rule 10 reads.
   **Per-day source selection**: a date ≤ today + 15 → forecast; any later date →
   normals (2a + 2b); a trip that straddles the boundary gets both, each day labelled.
   **Every weather line is stamped** with its mode and date — `… · Open-Meteo
   forecast · as-of 2026-09-02` or `… · 5-yr normals + climate model · as-of
   2026-09-02` — in `brief.weather` and in any per-day weather note; the T-7 row of
   the pre-departure ladder (output-template.md) re-runs step 3 and re-applies rule 10.
   Run all of these with `--max-time 90`, one city per call, and assert the body is
   non-empty JSON before reading numbers out of it — an empty 200 looks identical
   to a stall.
4. Sunrise/sunset for golden-hour scheduling — preferred path is
   `python3 scripts/route_tools.py sun plan.geo.json --write` (per-day fetch keyed on
   the day's first stop — the **last** stop on a moving day, or the day's `sun_stop`
   when set —, cache, the sanity rules below applied for you, canonical `sun`
   string written into the plan, a WARN per skipped/rejected day with its date and a
   **non-zero exit** when there is any; see scheduling.md rule 7). Redirect its
   output to a file rather than piping — a pipe makes `$?` the last command's exit
   and loses sun's non-zero signal (scheduling.md rule 7). **Run it before
   writing any sunrise/golden-hour prose**: the local clock comes from tzdata, which
   knows about time-zone changes you don't (Morocco returns to UTC+0 on 2026-09-20 —
   the tester's hand-written times were an hour off for all ten days); `sun`'s
   output is the truth, prose follows it.
   Manual fallback — only when python itself cannot run, so `plan_lint` cannot either;
   type the result in the canonical `sun` shape and stamp the day `note` "sun
   hand-fetched" (keyless, any future date; `tzid`
   on the `/json` endpoint verified working 2026-08-01):
   `curl -s "https://api.sunrise-sunset.org/json?lat={lat}&lng={lon}&date={YYYY-MM-DD}&formatted=0&tzid={Area/City}"`
   The service requires **visible attribution** wherever the data is shown — put
   "日出日落数据 / sunrise-sunset.org" in the plan footer — and answers heavy use with
   HTTP 429 + Retry-After, so fetch once per city (plus one fetch on each side of a
   daylight-saving switch), not once per day.
   **Sanity rules — the API fails open.** A malformed or missing `lat`/`lng`/`date`
   (a shell variable that didn't split, a stray quote) does **not** error: it
   returns today's times for 0°,0° with `"status":"OK"` — 07:59/20:09, day length
   12 h 09 m — which looks perfectly plausible for a plan and nearly went onto eight
   Norwegian day cards. Don't trust a response unless: `status` is `OK`; two
   different cities or two different dates give **different** times; and the day
   length is possible for that latitude and month (60°N in early October ≈ 11 h and
   shortening by ~5 min a day; a flat 12 h that doesn't move from one date to the
   next is the equator, not your destination). Anything else → fix the request and
   re-fetch, or ship the day without `sun` rather than with a wrong one.
   From Python, `urllib` direct hits get **HTTP 403 without a User-Agent** — set one
   (`{"User-Agent": "trip-planner-skill/1.x (personal trip planning)"}`, which the
   script already does); curl works because it sends its own.
5. **Live conditions (same day)** — for a go / no-go decided the evening before or on
   the day (when, and what it decides: scheduling.md §Day types, "Weather-window
   day"). Two kinds of evidence, never the point forecast alone:
   - **The forecast and the forecaster's reasoning — US only** (✓ 2026-10, NWS keyless
     JSON; a User-Agent header is required — without one the API answers 403):
     `curl -s --max-time 30 -A "trip-planner-skill/1.x (personal trip planning)" "https://api.weather.gov/points/{lat},{lon}"`
     → `properties.forecastHourly` (a URL: fetch it for `properties.periods[]`, hour by
     hour) and `properties.cwa` (the forecast office — `gridId` is the forecast grid and can
     differ, Alaska for one) →
     `curl -s --max-time 30 -A "…" "https://api.weather.gov/products/types/AFD/locations/{cwa}/latest"`
     → `productText`, the Area Forecast Discussion: the forecaster's timing and
     confidence in prose. Outside the US: the national weather service's forecast text
     in the browser pane ⚡.
   - **The present — worldwide**: the nearest airport's METAR (✓ 2026-10, keyless,
     plain text, one line per station — wind, visibility, cloud):
     `curl -s --max-time 30 -A "trip-planner-skill/1.x" "https://aviationweather.gov/api/data/metar?ids={ICAO}"`;
     satellite imagery in the browser pane — RAMMB SLIDER
     (`https://rammb-slider.cira.colostate.edu`, GOES-East / GOES-West / Himawari ⚡);
     for a view, the official webcam (§Hazard feeds).
   Stamp each line with what was read and when: `… · METAR {ICAO} {HHMM}Z + NWS AFD ·
   as-of YYYY-MM-DD`.

## FX — ✓
`curl -s "https://api.frankfurter.dev/v1/latest?base={HOME}&symbols={DEST}"`
(ECB daily fix). Stamp rate + date once in the budget table; don't re-fetch per line.
**Coverage is ~30 major currencies only** (`/v1/currencies` lists them: EUR USD GBP
JPY CNY KRW THB AUD CAD MXN TRY … — no MAD, VND, EGP, TND, DZD, KHR, LAK, LKR, NPR,
UZS…). An unsupported symbol does **not** error: the call returns HTTP 200 and the
`rates` object simply lacks that key (`symbols=VND,USD` → `{"USD": …}` alone), so a
script that reads `rates[DEST]` blindly takes the wrong currency (Vietnam) or ships
no rate at all (Morocco). Therefore:
1. after any frankfurter call, **assert the destination key is present** in `rates`;
2. missing → fall back to `curl -s "https://open.er-api.com/v6/latest/{HOME}"`
   (keyless, ~160 currencies, daily; read `rates.{DEST}` and `time_last_update_utc`)
   — check the key there too;
3. write which source you used into `meta.fx`, e.g.
   `1 CAD = 6.70 MAD (open.er-api.com, 2026-08-15 — MAD not on frankfurter)`.

A third failure mode: frankfurter can answer a `?base=…&symbols=…` call with an
**empty body** — 0 bytes, HTTP 200, no error text — so the JSON parse fails on
nothing rather than on a missing key. Retry the same date with another base
(`base=EUR`) and cross-multiply to the pair you need
(`HOME→DEST = (EUR→DEST) / (EUR→HOME)`); if that is what produced the number, say so
in `meta.fx`, e.g. `1 CAD = 108.4 JPY (frankfurter.dev via EUR cross, 2026-08-15 —
direct CAD call returned an empty body)`. An empty body twice → go to step 2's
fallback.
Closed currencies (MAD, TND, DZD, …) also get one line in the money brief: not
buyable before departure, not exportable — exchange on arrival / ATM.

**Money safety — the recipes behind `brief.money`** (the card's five lines and their
order live in output-template.md §Brief templates; the numbers below are that card's
line numbers — source notes, not a second list):
1. DCC: always "charge in local currency" at POS and ATM; the machine's conversion
   costs 3-8 % per swipe. Universal — country sections only record exceptions.
2. Card FX fee: read the issuer's foreign-transaction fee (0 % on a travel card,
   1.5-3 % on most others); unknown → the budget's buffer row takes +1.5-3 % with
   that reason in its note.
3. ATMs: bank-lobby machines, shield the PIN, few large withdrawals; write the
   country's typical fee and per-withdrawal cap ⚡ ("check on arrival" when unknown).
4. Cash: two cards on different networks (Visa + Mastercard; UnionPay where it
   works), the cash number sized to the destination's cash habit, and the
   cash-declaration threshold on entry — EU ≥ €10,000 · US > $10,000 · Japan
   > ¥1,000,000 ⚡ (verify per trip); confusable banknotes get one line where they
   exist (Vietnam ₫20,000 vs ₫500,000).
5. Acceptance: which of Visa / Mastercard / UnionPay / Alipay+ / WeChat Pay work
   where — one line.
Origin block, mainland-China departure only: UnionPay vs Visa/MC acceptance,
Alipay+ / WeChat cross-border coverage ⚡, foreign cash pre-ordered 1-2 days ahead
at home.

## Shopping requests
A "buy it there" wish is a price comparison and a version check.
- **Price it against the home market's sale price, not its list price**: today's home
  price (official store, a marketplace promotion) against the destination's tag plus
  its sales tax or VAT, less a tourist refund only where one applies, plus the card's
  FX fee (§FX, Money safety line 2). "Cheaper there" from a forum is not a number.
- **Identify the version by the box, not by folklore**: "the origin-country version is
  better" is forum folklore. A market version is read off its regulatory label and its
  **full** barcode, compared with the brand's own domestic site — a GS1 prefix (the
  first digits) proves only which GS1 office issued the code, not where or for which
  market the item was made (GS1, as of 2026-10). Worked cases: country-quick-notes.md
  §Japan, §USA.
- What travels on to the next border — the next country's entry rules, and the home
  country's allowance on the way back — is `brief.safety` line 6 (output-template.md
  §Brief templates).

## Visa / entry
Web search `{nationality} citizens visa {destination}` restricted to official
government/embassy domains — blogs and forums are how people miss rule changes.
Capture: visa type, fee, processing days (→ checklist), passport-validity rule
(the 6-month trap), onward-ticket requirement.
- **The yellow-fever certificate (ICVP) is an entry document — audit it with the
  visa**: the inputs are the departure country, every transit airport and every entry
  country — the passport is irrelevant (a Chinese passport departing Brazil for Kenya
  needs the ICVP: Brazil is a risk country, Kenya requires it from arrivals from one).
  For each read WHO Annex 1 (§Travel health below) — is it a risk country, and does it
  require the certificate from travellers arriving from one (transit footnotes: > 12 h / > 4 h / any duration /
  > 24 h in Brazil-Bolivia-Peru-Venezuela — read the footnote number on that country's
  row). A
  hit → checklist row "yellow-fever vaccine + ICVP", deadline departure − 10 days −
  clinic lead time.

## Travel advisory — ✓ (2026-09-03)
Primary source = the traveller's passport; one second source (US or UK, both keyless
JSON) every time; the stricter level drives the plan, a disagreement goes to
`unverified` (phase-1-brief.md §Advisory line).
- **US State Department** — `curl -s "https://cadataapi.state.gov/api/TravelAdvisories"`
  (✓ keyless JSON, ~220 entries): each row `Title` = "{Country} - Level N: …",
  `Category` = FIPS-style code(s) — Japan `JA`, Germany `GM`, Australia `AS`, China
  `CH`, NOT ISO-2 — `Updated` = as-of, `Link` = the full page. Filter by
  Title; one call covers every destination on the route.
- **UK FCDO** — `curl -s "https://www.gov.uk/api/content/foreign-travel-advice/{slug}"`
  (✓ keyless JSON): `details.alert_status` (`[]` = no alert; otherwise statuses such as
  `avoid_all_travel_to_parts`), `public_updated_at` = as-of, `details.parts[]` with the
  slugs `warnings-and-insurance` · `entry-requirements` · `safety-and-security` ·
  `regional-risks` · `health` · `getting-help` — the last four feed `brief.safety`,
  `brief.health` and `brief.emergency`.
- **中国领事服务网** — 旅行风险等级和安全提醒 (country pages under
  `cs.mfa.gov.cn/zggmcg/ljmdd/…/lxfxdjhaqtx/`) and the 安全提醒 list
  `https://cs.mfa.gov.cn/gyls/lsgz/lsyj/` — **browser pane only** (curl gets no
  response); 领保热线 12308 / +86-10-12308.
- **Smartraveller (AU)** — `https://www.smartraveller.gov.au/destinations` in the
  browser pane (an export API exists but is unverified).
- Other passports: the ministry's own advisory (Auswärtiges Amt, travel.gc.ca, MOFA
  Japan 海外安全情報 …) in the browser pane.
- **Level mapping**: US Level 4 = UK "avoid all travel" = CN 红色 / 暂勿前往 → stop and
  ask; US Level 3 = UK "avoid all but essential travel" = CN 橙色 / 谨慎前往 → the user decides
  with the line in front of them; "… to parts of" → every base, leg and day trip is
  checked against the named areas.

## Travel health — ✓ (2026-09-03)
- **CDC destination page** — `https://wwwnc.cdc.gov/travel/destinations/traveler/none/{country-slug}`
  (✓ static HTML, curl-readable; sections Travel Health Notices · Vaccines and
  Medicines · Non-Vaccine-Preventable Diseases · Stay Healthy and Safe, incl. "Eat and
  drink safely" · Healthy Travel Packing List · After Your Trip). One fetch per
  destination; the "recommended for most / some travellers" rows are the consult agenda.
- **TravelHealthPro (UK NaTHNaC)** — `curl -s -L -A "Mozilla/5.0" "https://travelhealthpro.org.uk/countries/{slug}"`
  (✓ static HTML; send a browser UA — some clients get 406 without one; slugs from
  `https://travelhealthpro.org.uk/countries`; the old `/country/{id}/…` form silently
  resolves to another country):
  Vaccine Recommendations · Malaria · Other Risks (dengue and co.).
- **WHO yellow fever, Annex 1** —
  `https://cdn.who.int/media/docs/default-source/travel-and-health/countries-with-risk-of-yellow-fever-transmission.pdf`
  (✓ PDF, last modified 2026-09-02): per country, risk of transmission and the
  certificate requirement for arrivals from risk countries, with the transit-hour
  footnotes. Certificate valid 10 days after vaccination, for life (2016 IHR change).
- **zh plans** cite the 海关总署 / 国际旅行卫生保健中心 (ithc.cn) 出入境健康提示 as the
  user-facing pointer; the ICVP is issued at ITHC clinics only.
- Rule: copy official recommendations and write the travel-clinic consult date; the
  plan never doses or prescribes (country-quick-notes.md §Travel clinic).

## Hazard feeds — ✓ (2026-09-03)
The season table (country-quick-notes.md §Hazard seasons) gives the odds; these feeds
give the present. Read them at Phase 1 for the season card and again at the T-14 /
T-7 / T-3 ladder rows.
- **GDACS** — `curl -s "https://www.gdacs.org/gdacsapi/api/events/geteventlist/SEARCH?eventlist=EQ;TC;FL;VO;WF"`
  (✓ keyless GeoJSON, the open event list — 94 events on test spanning a year of
  `fromdate`, only 4 with `iscurrent` = "true"; filter `iscurrent` / `todate` ≥ today
  and `country` or `iso3`; an orange tropical cyclone over Japan among them):
  `properties.eventtype` / `eventname` / `alertlevel` /
  `country`; show "GDACS" as attribution where the data is printed.
- **USGS earthquakes** — `curl -s "https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson&latitude={lat}&longitude={lon}&maxradiuskm=300&minmagnitude=5&starttime={YYYY-MM-DD}"`
  (✓ keyless GeoJSON).
- **NOAA NHC active storms** — `curl -s "https://www.nhc.noaa.gov/CurrentStorms.json"`
  (✓ keyless JSON, `activeStorms[]`; Atlantic + East Pacific).
- **JMA typhoons** — `curl -s "https://www.jma.go.jp/bosai/typhoon/data/targetTc.json"`
  (✓ 2026-10-02, keyless JSON: one row per tracked system — `tropicalCyclone` id,
  `typhoonNumber`, `category` (`LOW` = no longer a tropical cyclone; act on TD / TS /
  STS / TY), `issue`; per storm,
  `…/typhoon/data/{tropicalCyclone}/specifications.json` carries the name, then the
  analysis and forecast parts, each with `position.deg` = `[lat, lon]`, `validtime.JST`,
  `category.en` and `pressure` (hPa), plus `probabilityCircleRadius.km` on forecast
  parts and `stormWarning[].range.km` where present — ✓ 2026-10, parsed live)
  — the NW Pacific, which NHC does not cover. **Reading it against the trip**: at each
  `validtime` near a flight or ferry day, the great-circle distance from `position.deg`
  to the destination airport against that part's radii. On a forecast part
  `stormWarning` is the storm-warning area (暴風警戒域), whose radius JMA builds as
  probability circle + storm-wind radius — so compare with `stormWarning[].range.km`
  alone (largest sector when it is split); inside = the airport is within the possible
  storm-wind area. On the analysis part it is today's storm-wind radius. What follows is
  phase-1-brief.md §Hazard line — no km threshold of our own.
- **Wildfire and smoke (US)** — InciWeb incident pages (`https://inciweb.wildfire.gov`),
  the park's `https://www.nps.gov/{park_code}/planyourvisit/conditions.htm` for road
  closures, and an AQI number:
  `curl -s "https://air-quality-api.open-meteo.com/v1/air-quality?latitude={lat}&longitude={lon}&hourly=us_aqi,pm2_5&timezone=auto&forecast_days=2"`
  (✓ 2026-10-02, keyless) or the AirNow Fire and Smoke Map (`https://fire.airnow.gov`,
  browser).
- **View-dependent stops: official webcams over point forecasts** — a clear point
  forecast does not mean the bridge, crater or summit is visible (live case: a coastal
  bridge viewpoint sat in fog all afternoon under a "sunny" forecast). Look at the
  official webcam before leaving — NPS parks:
  `https://www.nps.gov/{park_code}/learn/photosmultimedia/webcams.htm`; observatory,
  city or bridge cams elsewhere — and put its link on that stop's row (advised, not
  linted).
- USGS Volcano Hazards API (`https://volcanoes.usgs.gov/vsc/api/`, alert levels —
  unverified), JMA warnings (警報), CWA, HKO, PAGASA, BoM, national fire services:
  browser pane.

## Optional keyed upgrades (only if the user already has env vars set)
- `AMADEUS_KEY` / `AMADEUS_SECRET` — Amadeus self-service flight/hotel search APIs.
- `SERPAPI_KEY` — Google Flights/Hotels as JSON without a browser.
Never ask the user to sign up for keys mid-plan; the keyless path is the default.

## Browser-pane reading recipes and known walls ⚡ (as of 2026-10)
- **Read accessible labels and visible text, not brittle selectors**: result rows on
  Google Flights and Google Maps carry price, times, stops and baggage notes in their
  accessible label (`aria-label`) — read them through the pane's accessibility-tree /
  find tools or `innerText` with a regex; generated class names churn. A screenshot
  is the last resort for reading a number.
- **A bot wall is read by the user, never bypassed**: a CAPTCHA, a Cloudflare-type
  challenge or a login wall stops the agent — hand the user the link, mark the row
  "verify on click", move to the next source; never retry a 403 in a loop. Seen in
  2026: primary ticket sellers and some resale sites, some hotel-chain brand sites,
  some mobile-carrier sites; one page of a site can read fine while another is
  walled, so a wall is recorded per page, not per site.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall