Ocas Voyage

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.

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:

$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

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

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

# 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

Update command

This skill self-updates every 24 hours via:

voyage.update

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