---
name: trip-itinerary
description: "Plan multi-day trips: search email for flight/rental/hotel confirmations, extract details from PDF attachments, build day-by-day agendas with driving times, attach activities/attractions, and compile a complete markdown itinerary."
version: 1.0.0
author: ShoNuff
platforms: [linux]
metadata:
  hermes:
    tags: [travel, itinerary, flight, hotel, rental-car, planning, attractions]
---

# Trip Itinerary Planning

Build a comprehensive trip itinerary from email confirmations, user preferences, and web research.

## Input Sources

1. **Email IMAP** — Search inbox for flight confirmations, rental car bookings, hotel/Airbnb emails, and attraction tickets
2. **PDF attachments** — Copa Airlines and other carriers send ticket receipts as PDF. Extract flight details with pdfminer.
3. **User preferences** — Departure location, who's traveling, luggage policy, TSA PreCheck/Global Entry status
4. **User's existing credentials** — Avis Wizard number, loyalty accounts, airline frequent flyer numbers

## Email Extraction Pattern

### Search strategy
- Search for airline names (Copa, American, Delta, United, Allegiant, Spirit, JetBlue, Southwest, Avianca, Latam)
- Search for destination city name ("Cartagena", "CTG", "Colombia")
- Search for rental car companies ("Avis", "Hertz", "Enterprise")
- Search for accommodation ("Airbnb", "Booking.com", hotel names, "Cartagena")
- Use `FROM` + `SUBJECT` IMAP search for precision, fall back to `BODY` search

### PDF processing
When an airline sends a PDF attachment:
```python
pip3 install pdfminer.six
from pdfminer.high_level import extract_text
text = extract_text('/tmp/ticket.pdf')
```
Then parse for: passenger name, flight numbers (CM###), dates/times, airport codes, layover duration, fare class, baggage allowance, booking reference.

## Departure Day Timeline

When building a departure timeline from a home city:
1. Calculate driving time: home → departure airport (include traffic buffer)
2. Add rental car return time (15 min)
3. Add shuttle/transit to terminal (15 min)
4. Apply TSA PreCheck timing (arrive 60-90 min before boarding, NOT 2+ hours — PreCheck takes ~10-15 min)
5. Factor in carry-on only vs checked bags (no bag drop means 10 min saved)
6. Pick up others along the way if applicable (add 15 min per pickup)
7. Include rest stop (~15-20 min) for a 4+ hour drive
8. Leave margin: 30 min buffer on arrival time

**Key formula:** For a 4.5h drive with PreCheck + carry-on + rental return, departure from home should be ~4.5h + 1.5h before boarding = 6h before flight time.

## Attractions Research

When the user asks for "cool" or "Kuehl" (likely meant "cool") attractions:
- Search by destination + keywords like "things to do", "family friendly", "must-see"
- Categorize by age group: kid-friendly (forts, animals, mud volcanoes, boats), adult (rooftop bars, nightlife, food tours), all-ages (historic sites, beaches)
- Include rainy day / indoor options
- Group into day-by-day suggestions with approximate time needed per activity

## Return Day & Customs

### US re-entry with Global Entry
- First port of entry into the US is where customs clearance happens (e.g. MCO even if continuing to Savannah by car)
- Global Entry kiosk: scan passport, fingerprint, answer declaration → ~2 min per person
- Children under 12 go through with a parent
- Total time with GE: ~10-15 min for a group of 4
- No duty concerns with carry-on only ($800/person limit)
- Mobile Passport Control app is a backup if GE kiosks are down (download CBP MPC app)

### Post-customs drive
- Shuttle to rental car lot (~15-20 min)
- Pick up return rental (one-way MCO → home city)
- Drive time same as departure (~4.5h)
- Rental car return at home airport (check hours — SAV open 7 AM - 1 AM)

## Rental Car Booking (Avis)

### Extracting Avis Wizard number
Avis emails show the Wizard # in the account statement email. The HTML may render it as hidden/obscured text. Search the raw HTML for `Wizard #:` followed by a `<span>` containing the number. The actual value may be partially redacted in output — get it from the raw HTML source. Search pattern:
```python
# In the raw HTML source:
m = re.search(r'Wizard\s*#[:\s]*<span[^>]*>(.*?)</span>', html, re.DOTALL)
```
### Avis Preferred Plus benefits
- Complimentary one-car-class upgrade when available
- Skip the counter — go straight to the car at Preferred locations
- Account number format appears to be `P72` prefix (partial, may vary)
- One-way rentals between airports are allowed
### Avis security code workflow

Avis now sends a one-time verification code by email when logging in. When the user initiates an Avis login, poll the IMAP inbox for the security code:

```python
conn.search(None, '(FROM "Avis" SUBJECT "verification code")')
```

Extract the code from the email body with regex and relay it to the user so they can complete login. After login, poll for the reservation confirmation.

### Extracting reservation details from Avis confirmation email

After login, Avis sends a Reservation Confirmation email. Search by:
```python
since = (datetime.now(timezone.utc) - timedelta(hours=24)).strftime("%d-%b-%Y")
status, data = conn.search(None, f'(FROM "Avis" SUBJECT "Reservation Confirmation" SINCE {since})')
```

Extract from plain-text body:
- **Reservation #:** Look for `#XXXXXXXXXX`
- **Vehicle:** `Ford Explorer or Similar`
- **Pickup/Drop-off:** Lines containing location name, date, and time
- **Cost:** Lines containing `Estimated Total:` (redact if user preference)
- **Mileage:** Look for `Unlimited`

### BCC pattern for group emails

When sending the itinerary to trip participants:
- Put the user in `To:`
- Put all other travelers in `Cc:`
- BCC the user's own address for a copy
- Send from `shonuff@germainebrown.com` with the Sho'Nuff signature and random closing quote
- Use SMTP port **2525** on mail.germainebrown.com (not 587 — blocked by netcup)
- **Do NOT include rental car costs in the itinerary when sending** — the user explicitly asked to remove dollar amounts before sharing with the group. If costs are present in the itinerary document, strip them out before sending.

### Sending itinerary to additional recipients

When the user asks to send the itinerary to someone who was NOT in the original travel group (e.g. `browo955@yahoo.com`), send to the new email as `To:` with BCC to the user. Do not add them to the CC list of the original group email — send a separate message to the new recipient.

### Two Avis reservations for round trips

A one-way trip between two airports needs TWO separate Avis reservations:
- **Departure rental:** Home airport → MCO (one-way, same day as flight)
- **Return rental:** MCO → Home airport (one-way, same day as return flight)

Both emails arrive separately and have different reservation numbers. Extract both.

## Renter Information / One-Way Rentals

- Avis allows one-way rentals between airports
- Ford Explorer or similar (mid-size SUV) is standard for 4 people + luggage
- Unlimited mileage on most one-way rentals
- Two reservations needed: home airport → MCO (departure day), MCO → home airport (return day)

## Output Format

Save a comprehensive markdown file to `/root/.hermes/trips/<destination>-<year>.md` with:

- Flight schedule table (leg, flight#, date, departure, arrival, duration)
- Fare details and notes (baggage, PreCheck, GE)
- Departure day agenda with minute-by-minute timeline
- Attractions by category (must-see, kid-friendly, adult, rainy day)
- Estimated day-by-day table
- Return day agenda with customs/GE process
- Rental car plan with reservation numbers
- Colombia entry requirements (passport validity, visa status)
- Checklist with completed/crossed-off items
## Pitfalls

- **Allegiant / other budget airlines** send their itineraries via separate emails per confirmation number, not always in a consolidated ticket receipt. Search for each confirmation number individually.
- **Copa Airlines** sends PDF attachments for e-tickets. The PDF has passenger name, flight numbers, times, fare details, and ticket number. Always check for PDF attachments when searching Copa emails.
- **Avis security codes** — When booking Avis, the verification code arrives by email, not SMS. Poll the IMAP inbox immediately after a login attempt.
- **Avis Preferred Plus benefits** — Complimentary one-car-class upgrade when available. Skip the counter — go straight to the car at Preferred locations.
- **TSA PreCheck + Global Entry are separate programs** — PreCheck is for departure security screening, Global Entry is for re-entry customs. Both can apply to the same person but they're used at different points in the journey.
- **Carry-on only changes everything** — No bag check means arrive at airport 60-90 min before boarding instead of 2-3 hours. This shifts the entire departure timeline by up to an hour.
- **Return flights with early AM departures** — CTG → PTY at 6:20 AM requires leaving the Airbnb by 4:00 AM. Arrange transport the night before (taxi companies in Cartagena need advance booking).
- **Global Entry kiosk at MCO** — MCO has dedicated GE kiosks near the baggage claim area. Follow signs to "Global Entry / Mobile Passport Control" — NOT the regular customs line.
- **Airbnb late check-in** — Arriving at 11 PM needs advance coordination with the host. Notify them at least 2 days before.
- **Domain confusion** — The user has multiple domains (itpropartner.com, germainebrown.com, forefrontwireless.com). When searching for trip-related emails, search across ALL mail accounts the user has access to, not just the primary one. Flights/confirmations may come to any of: info@itpropartner.com, g@germainebrown.com, or other addresses.
- **Allegiant flights for other passengers may use their own email** — If Tina & Garrison booked separately, their confirmations went to their own email, not the user's. Ask the user to forward or share the details rather than spend time searching.
- **Screenshots from the user are NOT in IMAP** — When the user sends a flight itinerary screenshot via Telegram, it's stored in `/root/.hermes/cache/images/` as `img_<hash>.jpg`. Check that directory with terminal `ls` before asking for a re-send.
- **Do NOT delegate itinerary research to subagents that need web tools** — If web_search/web_extract are unavailable, the subagent will also fail. Do the research directly or use curl-based fallback from the parent session.
- **When the user sends a flight screenshot, confirm the exact flight times with the IMAP data** — Screenshots/flight info from the user may match what you already extracted from IMAP. Cross-reference and confirm rather than blindly accepting new data that contradicts the PDF extraction.
- **When extracting PDF attachments from airline emails, check for MULTIPLE PDFs in consecutive emails** — Copa Airlines sends separate ticket receipts (one PDF per passenger) in SEPARATE email messages with the same subject and timestamp. Both contain full flight details. The first PDF may be one passenger (e.g. Anita), the second (next email, same subject) the other (e.g. Germaine). Both confirm the same flights but with different passenger names and ticket numbers.
- **Copa Airlines confirmation code** — The Copa "Get ready for your trip to Kartagena" email mentions the reservation code (e.g. A4GSFD). The PDF e-ticket confirms the Order ID is the same code. Use this to search for related emails across all mail accounts.
- **Cancelled tasks (e.g. rental car in Cartagena) need explicit notes in the itinerary** — If the user says they're NOT planning to rent in a location, note it explicitly so you don't propose it again. Mark it as "Not planning to rent — using taxis/ride-shares" rather than just removing the section.
- **Airbnb address goes in the itinerary header** — When the user provides Airbnb info (image or text), extract the full address and any check-in/out times. Add them to the top of the itinerary document immediately so they're not forgotten.
- **Family logistics** — When traveling with a child (11yo) and a mixed-ex family group (ex-wife, girlfriend), include kid-friendly activities as a separate section. The child's interests (forts, animals, mud volcanoes, boats) are a legitimate planning constraint.
- **Email the itinerary to all travelers** — After building the itinerary, email it from shonuff@germainebrown.com to the whole group. CC everyone.
- **Avis security code sent by email** — Avis sends login codes to shonuff inbox. Poll IMAP for them after a login attempt.
- **Two Avis reservations needed** — SAV→MCO one-way (departure) and MCO→SAV one-way (return). Both from separate confirmation emails.
