Interactive Menu#

When invoked interactively, present a two-level menu. See references/interactive-menu.md for the full menu structure.

When to Use#

• Travel planning and itinerary construction
• Flight, hotel, and activity research
• Booking coordination across multiple providers
• Travel document and requirement checking
• When any skill needs travel-related data
• Plan a multi-day trip with itinerary; build or optimize a travel itinerary
• Search for flights (one-way, round-trip, multi-city); find cheapest dates to fly
• Recommend lodging, restaurants, or activities for a trip
• Manage reservation planning and checklists

When NOT to Use#

• Calendar management (use Sands)
• Restaurant reservations (use Spot)
• General web research (use Sift)
• Travel insurance or financial planning
• Generic travel inspiration with no planning intent
• Points-only optimization (use Rally)
• Visa, customs, or medical-travel compliance as primary task

Voyage#

Voyage builds complete, constraint-aware travel itineraries — taking a destination, dates, budget, dietary preferences, and pace, then assembling lodging, dining, and activity recommendations into a logistics-optimized plan that is ready for reservation without auto-booking anything. It never presents uncertain operating hours or availability as confirmed fact, and surfaces cost implications throughout so the plan remains honest about what it actually knows.

Responsibility boundary#

Voyage owns travel planning, itinerary construction, and reservation management.

Voyage does not own: web research (Sift), preference persistence (Taste), communications (Dispatch).

Lodging search#

When the user needs lodging recommendations, all configured sources fire in parallel. Results are merged into a unified comparison table.

SourceProvidesRequiresExpedia webHotel/package search, total-cost breakdownNone — always availableMarriott Strider MCPReal Bonvoy inventory, award nights, elite upgrades, mobile keymcp-marriott installed + configured (profile marriott MCP server) + Bonvoy OAuth login ( login tool or MARRIOTT_EMAIL/MARRIOTT_PASSWORD env)Marriott AI / FlyAIPackage bundling DEAD (2026-08-23, DNS NXDOMAIN) — do not use—Google HotelsStructured results table (price/rating/amenities), search-onlyagent-browser CLI1StayReal hotel booking with confirmation numbers, loyalty program eligible, 300K+ properties in 140+ countries. Full lifecycle: search → details → book → lookup/cancelMCP connector 1stay configured (Streamable HTTP) + Bearer API key for bookingHotelOraclePrice trends (calendar), area guides, cross-site price comparison, nearby attractions — research enrichment only, no bookingDirect Streamable HTTP: https://tooloracle.io/hotel/mcp/ (free tier, no key); configured as profile hoteloracle MCP serverHotelsByDayDay-use rooms (10AM–5PM) and work passes — unique vertical not on other platforms. Python harness: scripts/hotelsbyday_search.py. Also night stays (beta, limited inventory)No credentials required; uses web harnessLetsFGFlight + hotel search with real booking (real PNR / confirmation); free-cancellation pay-later hotel rates, 5%-now/rest-to-hotelletsfg auth card-on-file token (nothing charged); see references/letsfg.mdSiftDestination info, activities, local knowledge, anything platforms don't coverSift skill installed

Results ranked by: total real cost → loyalty/points value → cancellation flexibility → location fit.

See references/lodging-sources.md for per-source patterns and failure modes.

GoPlaces cooperation (optional): If ocas-goplaces is installed, Voyage calls it to resolve ambiguous location input before search (geocoding, distance checks, neighborhood context). If not installed, Voyage surfaces unresolved location ambiguity to the user rather than guessing. Voyage checks for GoPlaces at runtime using the platform skill registry.

Total cost rule: Always surface headline price + taxes + mandatory fees + cancellation flexibility before recommending. Never present a listing price as booking-final. See references/total-cost.md.

Booking gate rule: Never present an option as "ready to book" without: price re-check complete, cancellation terms stated, and explicit user approval. See references/booking-gates.md.

Flight search#

When the user needs flight options, Voyage uses the fli library to query Google Flights data directly. No API key or browser required.

LetsFG (booking-capable complement): For the broadest price scan (budget carriers, OTAs, stable repeat pricing) and actual booking without OTA checkout redirects — flights and free-cancellation pay-later hotels — use LetsFG ( pip install letsfg, one-time letsfg auth card-on-file setup, nothing charged; NEVER use letsfg register/ setup-payment, those create a paid Developer API billing account). Hotel bookings carry a 5% non-refundable reservation fee. Run fli first (no credentials); add LetsFG results when a token exists or the task involves booking. See references/letsfg.md.

For quick searches, use the bundled script:

bash

$HERMES_PY ~/.hermes/skills/ocas-voyage/scripts/flight_search.py SFO JFK 2026-06-16
$HERMES_PY ~/.hermes/skills/ocas-voyage/scripts/flight_search.py SFO LGA 2026-06-16 SFO 2026-06-18 --limit 5

See references/flight-search.md for the full fli API calling convention (including common pitfalls) and references/flights.md for date search, multi-airport, and multi-city patterns.

Ontology types#

Voyage works with these types from spec-ocas-ontology.md:

• Place — venues, airports, hotels, restaurants, attractions. Extracted during destination research and itinerary construction.
• Concept/Event — trips and travel events (departure, arrival, check-in, activity). Stored in itinerary records.
• Concept/Action — booking actions (reserved, cancelled, modified). Recorded in Action Journals.
• Entity/Person — travel companions mentioned during trip planning.

Voyage maintains its own trip and itinerary state in {agent_root}/commons/data/ocas-voyage/. Entity observations are recorded in journal outputs for downstream Chronicle ingestion.

Commands#

• voyage.plan.trip — create a full trip plan from destination, dates, and constraints
• voyage.recommend.lodging — parallel lodging search across Expedia, Marriott Strider, Marriott AI, Google Hotels, 1Stay, and HotelsByDay (day-use rooms). HotelOracle used for price calendar and cross-site comparison research. Returns unified comparison table with total-cost breakdown and booking-gate summary.
• voyage.recommend.flights — search Google Flights for one-way, round-trip, multi-city, or date-range queries. Returns structured flight options with pricing, timing, and airline details.
• voyage.recommend.food — restaurant recommendations based on route and preferences
• voyage.recommend.activities — activity recommendations based on interests and logistics
• voyage.optimize.itinerary — optimize an existing itinerary for feasibility and logistics
• voyage.status — current plan state, pending reservations, open decisions
• voyage.journal — write journal for the current run; called at end of every run
• voyage.update — pull latest from GitHub source; preserves journals and data

Workflow#

The Voyage pipeline follows: research → search → compare → recommend → persist.

1. Research destination via Sift (example: "best neighborhoods in Lisbon for food lovers")
2. Search lodging in parallel across all providers; HotelsByDay covers day-use rooms (10AM–5PM), HotelOracle enriches with price calendars and cross-site comparison where available, 1Stay provides booking
3. Search flights via Google Flights
4. Compare options with total-cost breakdown
5. Recommend with evidence-linked rationale (because each recommendation names the specific attributes that justify it)
6. Persist plan state and write journal

Run completion#

After every Voyage command:

1. Persist plan state, recommendations, and reservation details to local files
2. Log material decisions to decisions.jsonl
3. Write journal via voyage.journal

Invariants#

• Never present uncertain operating hours or availability as confirmed
• Respect dietary constraints in all food recommendations
• Budget awareness throughout — surface cost implications
• Reservation-ready means actionable, not auto-booked (unless explicitly enabled)

Error Handling#

FailureDetectionResponseLodging source unavailableAPI timeout or error from any MCP/lodging sourceSkip source; continue with remaining sources; log warningFlight search failurefli library raises exception or returns emptyReport error; suggest manual Google Flights checkDocker unavailable (Inception)Docker daemon not runningLog degraded: docker; return error with diagnostic infoGoPlaces unavailableSkill registry check failsSurface location ambiguity to user; do not guessGoogle Places API unavailableAPI key missing or quota exceededSurface warning; ask for manual estimate

Storage layout#

See references/storage-and-config.md for the directory structure and default config.json.

OKRs#

See references/okrs.md.

Optional skill cooperation#

• Sift — all open web research: destination info, restaurant picks, activity recommendations, local knowledge. Voyage delegates to Sift via Sift's search stack; does not do raw web searches itself.
• GoPlaces ( ocas-goplaces) — location enrichment: geocoding, distance-to-airport/center, neighborhood context, disambiguation of ambiguous location input. Check at runtime: platform skill registry query | grep goplaces. If not installed, flag ambiguity to user.
• HotelOracle ( io.tooloracle/hoteloracle via Glama MCP Gateway) — price calendar trends, cross-site price comparison, area guides, nearby attractions. Research-only; no booking capability. Enriches hotel details with Google Hotels data.
• Taste — preference-aware recommendations (read-only)
• Weave — trip companion context from social graph (read-only)
• Chronicle — entity observations emitted via journal signal payloads
• Vesper — travel schedule briefs delivered directly to ocas-vesper's intake directory ( {agent_root}/commons/data/ocas-vesper/intake/) so the morning/evening briefing aggregates pending trip details. See references/vesper-intake-delivery.md.

Journal outputs#

Action Journal — all planning, recommendation, and reservation runs.

When entities are encountered during a run, include structured entity observations in decision.payload:

• entities_observed — list of entities encountered (Place, Concept/Event, Concept/Action, Entity/Person), each with type, name, and context
• relationships_observed — connections between entities (e.g., a person associated with a trip, a restaurant located in a destination)
• preferences_observed — user preferences inferred from planning choices (e.g., budget range, dietary needs, pace preference)

Each entity observation must include a user_relevance field:

• user — entity is directly related to the user's world (destinations, hotels, companions, reservations). Most Voyage entities are user-relevant since they represent the user's actual travel plans and destinations.
• agent_only — entity encountered incidentally (e.g., a landmark mentioned only as a routing waypoint, not as a destination)
• unknown — relevance is unclear

Initialization#

On first invocation of any Voyage command, run voyage.init. See references/initialization.md for the full 10-step procedure including Marriott MCP setup, Google Hotels setup, flights library install, optional credentials, and GoPlaces check.

Background tasks#

Job nameMechanismScheduleCommandvoyage:updatecron0 0 * * * (midnight daily)voyage.updatetext

# Task declared in SKILL.md frontmatter metadata.{platform}.cron

Self-update#

voyage.update pulls the latest package from the source: URL in frontmatter. Runs silently — no output unless the version changed or an error occurred. See references/self-update.md for the full 7-step procedure.

Visibility#

public

Gotchas#

• GoPlaces is optional, not required — If ocas-goplaces is not installed, Voyage surfaces unresolved location ambiguity to the user rather than guessing. The skill works normally but location resolution depends on user input.
• Total cost rule is mandatory — Always surface headline price + taxes + mandatory fees + cancellation flexibility before recommending. Presenting a listing price as booking-final violates the booking gate rule.
• Flight prices are volatile — Always include an "as of" timestamp in flight search results. Prices change frequently and are never guaranteed. The fli library queries Google Flights in real-time.
• Multi-city searches may time out — For complex multi-leg itineraries, search legs individually and combine results rather than using a single multi-city query.
• Reference files are authoritative over SKILL.md — If a concept is described in both SKILL.md and a reference file, the reference file wins. Always read the relevant reference before executing a workflow.
• Integration hygiene (operator, 2026-08-22): after integrating any new service into Voyage, run a rationalization/health scan over ALL integrated APIs and MCPs — verify each is healthy and working, and document what each is used for in the reference files. Fix broken ones rather than leaving them listed.

Support File Map#

FileWhen to readreferences/voyage_schemas.mdBefore creating plans, itineraries, or reservations; when validating data structuresreferences/itinerary_constraints.mdBefore constraint application or optimization; when checking feasibility rulesreferences/recommendation_style.mdBefore generating recommendations; when checking tone and format guidelinesreferences/journal.mdBefore calling voyage.journal; at end of every runreferences/flights.mdBefore any flight search; when checking API patterns, airport resolution, or failure modesreferences/letsfg.mdBefore using LetsFG for flight/hotel search or booking; auth setup, guardrails, SDK patternsreferences/lodging-sources.mdBefore lodging search; when checking per-source patterns and failure modesreferences/flight-search.mdBefore any flight search; when checking API patterns, airport resolution, or failure modesreferences/storage-and-config.mdWhen inspecting or configuring the on-disk data files and default configreferences/okrs.mdWhen reviewing OKR definitions or scoring skill performancereferences/initialization.mdOn first use; Marriott MCP setup, flights library install, GoPlaces checkreferences/self-update.mdWhen running voyage.update; full 7-step update procedurereferences/vesper-intake-delivery.mdAfter a trip is confirmed; write the brief to Vesper's intake directoryreferences/plans/trip-planning.plan.mdBefore a multi-step trip-planning request; destination research → itinerary → accommodation bundlingscripts/hotelsbyday_search.pyBundled HotelsByDay harness for day-use rooms,and night stays; call via venv Python for quick searchesscripts/flight_search.pyReusable flight search script; call via venv Python for quick one-off searches

Update command#

This skill self-updates every 24 hours via:

bash

voyage.update

This pulls the latest version from GitHub. Voyage has no background operational tasks, so there is nothing to restart.