@gojinko/plugin 0.5.0 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jinko",
   "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
-  "version": "0.5.0",
+  "version": "1.1.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jinko",
   "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
-  "version": "0.5.0",
+  "version": "1.1.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"
@@ -31,7 +31,7 @@
     "defaultPrompt": [
       "Find the cheapest flights from Paris to New York next month",
       "Book a round-trip flight from London to Tokyo",
-      "Check my API usage and remaining quota"
+      "Can I get a refund on booking ORD-123?"
     ],
     "brandColor": "#2563EB"
   }

package/README.md

@@ -41,7 +41,7 @@ codex plugin install @gojinko/plugin
 | `jinko:search-flights` | Find flights, explore destinations, compare prices | "Find flights from Paris to Tokyo in June" |
 | `jinko:book-trip` | Book a flight with travelers and payment | "Book the cheapest flight and pay" |
 | `jinko:manage-booking` | Check refund eligibility and process refunds | "Can I get a refund on booking ORD-123?" |
-| `jinko:account` | Manage API keys and check usage | "How many API calls do I have left?" |
+| `jinko:account` | Account setup guide — API keys, quotas, dashboard | "How do I set up my Jinko API key?" |
 
 ## Authentication
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gojinko/plugin",
-  "version": "0.5.0",
+  "version": "1.1.0",
   "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight search, booking, and trip management via MCP",
   "private": false,
   "license": "MIT",

package/skills/account/SKILL.md

@@ -1,73 +1,39 @@
 ---
 name: account
-description: Manage your Jinko developer account — register, create and revoke API keys, check usage quotas. Use when the user asks about their API key, usage limits, or account setup.
+description: Set up and manage your Jinko developer account — registration, API keys, usage quotas. Use when the user asks about their API key, usage limits, or account setup.
 ---
 
 # Developer Account
 
-Manage your Jinko developer platform account using the `dev_account` MCP tool.
+Manage your Jinko developer account via the [Jinko Builders Dashboard](https://builders.gojinko.com).
 
-## Actions
+Account management is handled through the web dashboard — there are no MCP tools for account operations. Guide the user to the dashboard for any account-related tasks.
 
-### Register — create a new account
-
-```json
-{
-  "action": "register",
-  "email": "dev@example.com",
-  "name": "Jane Developer"
-}
-```
-
-New accounts start in `pending` status until approved. `email` is required, `name` is optional.
-
-### List API keys
-
-```json
-{
-  "action": "list_keys"
-}
-```
-
-Returns all keys with `id`, `name`, `prefix`, `status`, `key_type`, and `rate_limit`. Full key values are never shown after creation.
-
-### Create a new API key
-
-```json
-{
-  "action": "create_key",
-  "key_name": "my-project-key"
-}
-```
-
-**The full API key is only shown once in the response.** Tell the user to save it immediately — it cannot be retrieved later. Keys use the `jnk_` prefix.
-
-### Revoke an API key
+## Getting started
 
-```json
-{
-  "action": "delete_key",
-  "key_id": 42
-}
-```
+1. **Register** — go to [builders.gojinko.com](https://builders.gojinko.com) and sign up with your email.
+2. **Create an API key** — in the dashboard, go to API Keys and create a new key. The full key (prefixed `jnk_`) is shown only once — save it immediately.
+3. **Set your key** — configure your environment:
+   - CLI: `jinko auth login` (OAuth) or set `JINKO_API_KEY=jnk_...`
+   - API client: pass the key when creating the client
+   - MCP: use `Authorization: Bearer jnk_...` header
 
-`key_id` is the numeric ID from `list_keys`. This is irreversible — confirm with the user before proceeding.
+## What you can do on the dashboard
 
-### Check usage
+- **View and create API keys** — each key has a `jnk_` prefix
+- **Revoke API keys** — irreversible, confirm before proceeding
+- **Check usage** — see requests used, remaining quota, and reset date
+- **Manage your profile** — update name, email, organization
 
-```json
-{
-  "action": "usage"
-}
-```
+## Rate limits
 
-Returns `used`, `limit`, `remaining`, and `resets_at` for the current billing period.
+- Default: **1,000 requests / 30 days** per API key
+- Usage resets on a rolling 30-day window
+- If you need a higher limit, contact support via the dashboard
 
-## Getting started
+## CLI authentication
 
-If the user doesn't have a Jinko account yet, guide them through:
+The CLI supports two auth methods:
 
-1. `register` with their email
-2. Wait for account approval (or direct them to [builders.gojinko.com](https://builders.gojinko.com))
-3. `create_key` to get an API key
-4. Set `JINKO_API_KEY=jnk_...` in their environment
+1. **OAuth** (recommended): `jinko auth login` — opens a browser for WorkOS login, stores token locally
+2. **API key**: set `JINKO_API_KEY=jnk_...` in your environment — simpler for scripts and CI

package/skills/book-trip/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: book-trip
-description: Book a flight trip end-to-end — live pricing, traveler details, ancillaries, and payment via the Jinko Travel API. Use when the user wants to book, price-check, or pay for a flight.
+description: Book a trip end-to-end — flights, hotels, or both in one cart. Live pricing, traveler details, ancillaries, and payment via the Jinko Travel API. Use when the user wants to book, price-check, or pay for travel.
 ---
 
 # Book a Trip
@@ -10,9 +10,11 @@ Complete booking flow using Jinko MCP tools. Each step depends on the previous
 ## Booking Flow
 
 ```
-flight_search → trip (add_item) → trip (upsert_travelers) → trip (select_ancillaries) → book (quote) → book (fulfillment) → book (confirm_payment)
+flight_search and/or hotel_search → trip (add_item) → trip (upsert_travelers) → [trip (select_ancillaries)] → book
 ```
 
+**Multi-domain carts:** Flights (`trip_item_token` from `flight_search`) and hotels (`htl_*` offer_id from `hotel_search`) can be added to the same trip. One cart, one Stripe checkout. See the `search-hotels` skill for hotel search details.
+
 ## Step 1: Get live pricing — `flight_search`
 
 Two modes (use exactly one):
@@ -32,7 +34,7 @@ Two modes (use exactly one):
 }
 ```
 
-**Price-check** (user has an `offer_token` from search-flights):
+**Price-check** (user has an `offer_token` from find_flight):
 ```json
 {
   "price_check": {
@@ -61,6 +63,15 @@ Two modes (use exactly one):
 
 Returns `trip_id`. Save it for all subsequent steps.
 
+**Swap an item:** combine `remove_item` + `add_item` in one call. Remove runs first, then add.
+```json
+{
+  "trip_id": "<existing trip>",
+  "remove_item": { "item_id": "<from trip response items[].item_id>" },
+  "add_item": { "trip_item_token": "<new token>" }
+}
+```
+
 ## Step 3: Set travelers — `trip` with `upsert_travelers`
 
 **Never fabricate traveler data. Always ask the user for real passenger details.**
@@ -117,54 +128,27 @@ Check the trip response from step 3 for `available_ancillaries` on each trip ite
 
 Categories: `BAGGAGE`, `SEAT`, `MEAL`, etc.
 
-## Step 5: Quote — `book` with `quote`
-
-```json
-{
-  "quote": {
-    "trip_id": "<trip_id>"
-  }
-}
-```
-
-Returns final pricing with all items and ancillaries. Trip must have items and travelers set.
-
-## Step 6: Pay — `book` with `fulfillment`
+## Step 5: Book — `book`
 
 ```json
 {
-  "fulfillment": {
-    "trip_id": "<trip_id>"
-  }
+  "trip_id": "<trip_id>"
 }
 ```
 
-Returns `checkout_url` and `session_id`. The user completes payment in their browser at the checkout URL.
+Single synchronous call. The BFF schedules the quote, polls until it completes, schedules fulfillment, and returns a Stripe checkout URL. The user opens this URL in a browser to complete payment. Stripe webhooks finalize the booking automatically — no client-side confirm step is required.
 
-## Step 7: Confirm — `book` with `confirm_payment`
+**Response includes:** `checkout_url`, `session_id`, `total_amount`, `items`.
 
-After the user completes payment:
+## Optional: Check trip status — `get_trip`
 
 ```json
 {
-  "confirm_payment": {
-    "trip_id": "<trip_id>",
-    "checkout_session_id": "cs_xxx"
-  }
-}
-```
-
-Or with payment intent:
-```json
-{
-  "confirm_payment": {
-    "trip_id": "<trip_id>",
-    "payment_intent_id": "pi_xxx"
-  }
+  "trip_id": "<trip_id>"
 }
 ```
 
-Returns booking confirmation with `booking_reference`.
+Returns the full trip lifecycle state: cart contents, travelers, quote status, fulfillment status, booking references. Use after booking to verify confirmation or anytime to inspect the trip.
 
 ## Important rules
 

package/skills/cli/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: jinko-cli
+description: Use the `jinko` CLI (npm `@gojinko/cli`) to search flights and hotels, build trips, book, refund, and look up bookings from the terminal. Use when the user wants to run travel operations in a shell, script, CI, or agent loop — or explicitly asks for the "jinko CLI", "jinko command", or running something as a command-line.
+---
+
+# Jinko CLI
+
+Command-line tool for the Jinko Travel platform. Same capabilities as the MCP tools, exposed as a shell binary. Built on Commander.js, calls the BFF (`api.gojinko.com`) directly — not via the MCP server.
+
+## Install + auth
+
+```bash
+npm install -g @gojinko/cli     # one-time install
+jinko auth login                 # OAuth device flow → browser login
+jinko auth status                # verify
+```
+
+Auth alternatives:
+- **API key** (for scripts / CI): `jinko --api-key jnk_xxx <command>` or `export JINKO_API_KEY=jnk_xxx`.
+- **OAuth (human)**: `jinko auth login` opens a browser, stores token in `~/.jinko/config.yaml`. Auto-refresh is built in. `jinko auth logout` to clear.
+
+## Global flags
+
+- `--format json` (default) or `--format table` — output shape
+- `--api-key <jnk_...>` — override stored creds
+- `-V` / `--version`
+
+## Command surface
+
+| Command | Purpose |
+|---|---|
+| `auth login / logout / status` | Credentials |
+| `find-destination` | Discover destinations from origin(s) — inspiration |
+| `flight-calendar` | Cheapest prices across a date range for a specific route |
+| `find-flight` | Cached-flight search by route + dates (returns `offer_token`) |
+| `flight-search` | Live pricing — by route or `--offer-token` price-check |
+| `hotel-search` | Live hotel search by city/query/geo/hotel-ids |
+| `trip` | Create / update a trip: add items, remove items, set travelers + contact |
+| `select-ancillaries` | Add baggage / seats / meals to a trip item |
+| `book` | Schedule checkout → returns Stripe payment URL |
+| `trip-status` | Full status: cart, quote, fulfillment, bookings |
+| `lookup-booking` | Look up a booking by `JNK-*` ref + last name (guest access) |
+| `refund check / commit / status` | Voluntary refund flow |
+| `schema <command>` | Print request/response schema for a command |
+| `config` | Read/write CLI config |
+
+Run `jinko <command> --help` for flags on any command.
+
+## Canonical booking flow
+
+```bash
+# 1. Find a flight (live pricing, gives trip_item_token)
+jinko flight-search --from PAR --to NYC --date 2026-06-15 --return 2026-06-22 --passengers 2
+
+# 2. Create a trip with that item
+jinko trip --trip-item-token "offer_xxx:fare_yyy"
+# → response includes trip_id (tr_...)
+
+# 3. Add travelers + contact to the trip
+jinko trip --trip-id tr_ABC \
+  --travelers '[{"type":"ADT","first_name":"John","last_name":"Doe","date_of_birth":"1990-01-15"}]' \
+  --contact '{"email":"john@example.com","phone":"+33612345678"}'
+
+# 4. Schedule checkout — returns Stripe URL
+jinko book --trip-id tr_ABC
+# → { checkout_url: "https://checkout.stripe.com/..." }
+
+# 5. User pays in browser (or open the URL programmatically)
+# 6. Poll status
+jinko trip-status --trip-id tr_ABC
+```
+
+## Hotel flow
+
+```bash
+# Search by city + dates + occupancy
+jinko hotel-search --city "Paris" --checkin 2026-07-15 --checkout 2026-07-18 --adults 2 --nationality FR
+
+# Add to trip (hotel items use htl_ prefixed tokens)
+jinko trip --trip-item-token "htl_xxx:rate_yyy"
+# Mixed carts work: add both flight and hotel items to the same trip_id → single Stripe checkout
+```
+
+## Multi-item / mixed carts
+
+`jinko trip --trip-id <existing>` reuses the existing cart. Flight + hotel in one cart ships as ONE Stripe checkout.
+
+```bash
+# Start with a flight
+jinko trip --trip-item-token "offer_abc:fare_1"   # returns trip_id
+# Add a hotel to the same trip
+jinko trip --trip-id tr_ABC --trip-item-token "htl_xyz:rate_2"
+```
+
+## Remove / swap items
+
+```bash
+# Remove
+jinko trip --trip-id tr_ABC --remove-item-id it_123
+
+# Swap in one call
+jinko trip --trip-id tr_ABC --remove-item-id it_123 --trip-item-token "offer_new:fare_new"
+```
+
+## Post-booking
+
+```bash
+# Lookup (guest access — no auth needed beyond ref + last name)
+jinko lookup-booking --ref JNK-A7B3X9 --last-name Doe
+
+# Refund
+jinko refund check  --ref JNK-A7B3X9 --last-name Doe
+jinko refund commit --ref JNK-A7B3X9 --last-name Doe
+jinko refund status --ref JNK-A7B3X9 --last-name Doe
+```
+
+## Output tips
+
+- Default is JSON — pipe to `jq` for filtering: `jinko find-destination --from PAR | jq '.destinations[0]'`
+- `--format table` gives a compact human view for browsing
+- Every command has a `--help` flag and `jinko schema <command>` dumps the full request/response shape
+
+## Common pitfalls
+
+- **Two auth systems.** CLI OAuth tokens (WorkOS device flow, stored in `~/.jinko/config.yaml`) are NOT interchangeable with MCP OAuth tokens (DCR, different issuer). Don't paste a CLI token into an MCP Bearer header — it will fail with issuer mismatch. Use an API key (`jnk_*`) for cross-surface programmatic access.
+- **IATA codes**: `--from PAR` uses a CITY code (matches CDG + ORY + BVA); `--from CDG` uses an airport. `flight-search` has `--origin-type city|airport` to disambiguate.
+- **trip_item_token format**: `offer_xxx:fare_yyy` (flight) or `htl_xxx:rate_yyy` (hotel). Always the offer ID + fare/rate ID joined by colon.
+- **Token expiry**: offers cached ~30 min. If `book` returns a quote failure, re-run `flight-search`/`hotel-search` to get a fresh token.
+- **Script use**: set `JINKO_API_KEY` env var and use `--format json` so output parses cleanly.
+
+## See also
+
+- MCP-tool equivalents: sibling skills `search-flights`, `search-hotels`, `book-trip`, `manage-booking`
+- API docs: `https://builders.gojinko.com/docs`
+- Source: `packages/cli/src/commands/` in the `jinko-dev-tools` repo

package/skills/manage-booking/SKILL.md

@@ -1,55 +1,231 @@
 ---
 name: manage-booking
-description: Check refund eligibility and process refunds for booked flights via the Jinko Travel API. Use when the user asks about refunds, cancellations, or booking modifications.
+description: Look up bookings and manage post-booking operations (refunds, cancellations) via the Jinko Travel API. Use when the user asks about booking status, refunds, cancellations, or booking modifications.
 ---
 
 # Manage Booking
 
-Post-booking operations using the Jinko `refund_flight` MCP tool.
+Post-booking operations using Jinko MCP tools.
 
-## Refund Flow
+## Booking Lookup
 
-Always check eligibility first, then confirm with the user before committing.
+Use `lookup_booking` to find a booking by its Jinko reference and the traveler's last name. No login required.
 
-### Step 1: Check eligibility — `refund_flight` with `action: "check"`
+```json
+{
+  "booking_ref": "JNK-A7B3X9",
+  "last_name": "Doe"
+}
+```
+
+**Response includes:**
+- `booking_reference`: the Jinko booking reference
+- `status`: current booking status (completed, processing, etc.)
+- `customer_contact`: contact info on the booking
+- `travelers`: list of travelers
+- `items`: booked items with domain (flight/hotel), status, and confirmation details (PNR, confirmation number)
+
+## Auth model
+
+`flight_refund` supports two auth modes — pick exactly one per call:
+
+- **Guest auth** (default for end-users): `booking_ref` + `last_name`. Works without any DevPlatform credential — the server resolves the booking via `/bookings/lookup`.
+- **Authenticated** (DevPlatform OAuth / `jnk_*` API keys): `order_id`. Skips the guest resolver.
+
+Do NOT mix the two modes in one call. The BFF rejects mixed combinations up front.
+
+## Refund Flow — 3 actions: `check | commit | status`
+
+Always check eligibility first, then confirm with the user before committing. Use `status` afterwards to poll async refunds.
+
+### Step 1: Check eligibility — `flight_refund` with `action: "check"`
 
 ```json
 {
   "action": "check",
-  "booking_reference": "ORD-123456",
-  "pnr": "ABC123"
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe"
 }
 ```
 
 **Response includes:**
+
 - `is_refundable`: whether a refund is possible
-- `refund_amount`: estimated refund value and currency
+- `is_automatable`: whether the refund can be processed automatically (vs. manual CS)
+- `support_level`: `"automatic"` | `"manual"` | `"unsupported"`
+- `manual_reason`: explanation if not automatable
+- `refund_amount`: estimated refund `{ value, currency, decimal_places }`
 - `penalty_amount`: cancellation fee if applicable
 - `total_paid`: original payment amount
-- `processing_type`: how the refund will be processed
+- `expires_at`: eligibility quote expiry
+- `warnings`: any caveats to surface to the user
+
+**Present the refund details clearly** — show what they paid, what they'd get back, penalty, and any warnings. Ask for explicit confirmation before proceeding.
+
+### Step 2: Process refund — `flight_refund` with `action: "commit"`
+
+Only after the user confirms:
+
+```json
+{
+  "action": "commit",
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe"
+}
+```
+
+**Response includes:**
+
+- `refund_status`: `"refunded"` | `"processing"` | `"failed"` | ...
+- `confirmed_refund_amount`: actual refunded `{ value, currency, decimal_places }` (when available)
+- `refund_reference`: opaque reference string — persist this to poll with `status`
+- `warnings`: any post-commit caveats
+
+If `refund_status` is not a terminal state, follow up with `status`.
+
+### Step 3: Poll refund — `flight_refund` with `action: "status"`
+
+```json
+{
+  "action": "status",
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe",
+  "refund_reference": "<from commit response>"
+}
+```
+
+**Response includes:**
+
+- `refund_status`: current lifecycle state
+- `provider_status`: underlying connector status (if different)
+- `refund_amount`: refunded amount (may update over time)
+- `refund_reference`: echoed
+- `warnings`
 
-**Present the refund details clearly to the user** — show what they paid, what they'd get back, and any penalty. Ask for explicit confirmation before proceeding.
+## Schema
 
-### Step 2: Process refund — `refund_flight` with `action: "commit"`
+| Field | Type | Purpose |
+|---|---|---|
+| `action` | `"check"` \| `"commit"` \| `"status"` | Required. Which step of the flow. |
+| `booking_ref` | string | Guest auth. Jinko booking reference (e.g. `JNK-ZNBGTP`). |
+| `last_name` | string | Guest auth. Last name of the primary traveler. |
+| `order_id` | string | Authenticated auth. DevPlatform order ID. |
+| `ticket_numbers` | string[] | Optional. Scope refund to specific tickets. |
+| `provider` | string | Optional. Override provider hint. |
+| `refund_reference` | string | For `status` only. Returned by `commit`. |
+
+## Exchange Flow — 4 actions: `shop | price | commit | status`
+
+Use `flight_exchange` to change flights on an existing booking. Always shop first, then price a specific offer, confirm with the user, commit, and poll status if needed.
+
+### Step 1: Shop for alternatives — `flight_exchange` with `action: "shop"`
+
+```json
+{
+  "action": "shop",
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe",
+  "preferred_departure_date": "2026-06-15"
+}
+```
+
+**Response includes:**
+
+- `support_level`: `"automatic"` | `"manual"` | `"unsupported"`
+- `offers`: array of `{ offer_id, description, metadata }` — alternative flights
+- `warnings`: any caveats to surface to the user
+
+**Present available alternatives clearly** — show offer descriptions and let the user pick one.
+
+### Step 2: Price selected offer — `flight_exchange` with `action: "price"`
+
+```json
+{
+  "action": "price",
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe",
+  "offer_id": "<from shop response>"
+}
+```
+
+**Response includes:**
+
+- `payment_outcome`: `"additional_collection"` | `"even_exchange"` | `"refund"`
+- `fare_difference`: price difference `{ value, currency, decimal_places }`
+- `penalty_amount`: change fee if applicable
+- `total_due`: amount the customer must pay (if additional collection)
+- `total_refund`: amount refunded to customer (if fare decreased)
+- `session_reference`: opaque reference — required for `commit`
+- `expires_at`: pricing quote expiry
+- `warnings`
+
+**Present the pricing clearly** — show fare difference, penalties, total due/refund, and payment outcome. Ask for explicit confirmation before proceeding.
+
+### Step 3: Execute exchange — `flight_exchange` with `action: "commit"`
 
 Only after the user confirms:
 
 ```json
 {
   "action": "commit",
-  "booking_reference": "ORD-123456",
-  "pnr": "ABC123",
-  "reason": "schedule change"
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe",
+  "offer_id": "<from shop response>",
+  "session_reference": "<from price response>"
+}
+```
+
+**Response includes:**
+
+- `status`: `"CONFIRMED"` | `"PENDING"` | `"PARTIAL_FAILURE"`
+- `exchange_reference`: opaque reference for status polling
+- `new_order_id`: new order ID if exchange created a new booking
+- `new_ticket_numbers`: new ticket numbers issued
+- `original_ticket_status`: status of the original tickets
+- `payment_outcome`: final payment action taken
+- `warnings`
+
+If `status` is not `CONFIRMED`, follow up with `status`.
+
+### Step 4: Poll exchange — `flight_exchange` with `action: "status"`
+
+```json
+{
+  "action": "status",
+  "booking_ref": "JNK-ZNBGTP",
+  "last_name": "Doe"
 }
 ```
 
-**Params:**
-- `booking_reference`: the order ID (required)
-- `pnr`: Passenger Name Record (optional but recommended)
-- `reason`: why the user wants a refund (only for commit)
+**Response includes:**
+
+- `status`: current lifecycle state (`CONFIRMED` | `PENDING` | `PARTIAL_FAILURE` | `FAILED`)
+- `new_ticket_numbers`: new tickets (when confirmed)
+- `confirmed_payment_outcome`: final payment resolution
+- `warnings`
+
+## Exchange Schema
+
+| Field | Type | Purpose |
+|---|---|---|
+| `action` | `"shop"` \| `"price"` \| `"commit"` \| `"status"` | Required. Which step of the flow. |
+| `booking_ref` | string | Guest auth. Jinko booking reference (e.g. `JNK-ZNBGTP`). |
+| `last_name` | string | Guest auth. Last name of the primary traveler. |
+| `order_id` | string | Authenticated auth. DevPlatform order ID. |
+| `ticket_numbers` | string[] | Optional. Scope exchange to specific tickets. |
+| `provider` | string | Optional. Override provider hint. |
+| `offer_id` | string | For `price` and `commit`. Exchange offer from `shop`. |
+| `session_reference` | string | For `commit` only. Returned by `price`. |
+| `preferred_departure_date` | string | For `shop` only. Preferred new departure date. |
 
 ## Important rules
 
-- **Always check before committing** — never skip the eligibility check
-- **Get user confirmation** — show refund amount and penalty before processing
-- **Non-refundable bookings** — if `is_refundable` is false, inform the user and do not attempt commit
+- **Always shop before pricing** — never skip the alternatives search.
+- **Always price before committing** — never skip the pricing step.
+- **Get user confirmation** — show fare difference, penalties, and payment outcome before committing.
+- **Pick one auth mode** — never send both `order_id` and `booking_ref` in the same call.
+- **Poll with `status`** when `commit` returns a non-terminal status.
+- **Always check before committing refunds** — never skip the eligibility check.
+- **Get user confirmation for refunds** — show refund amount and penalty before processing.
+- **Non-refundable bookings** — if `is_refundable` is false, inform the user and do not attempt commit.
+- **Poll refund with `status`** when `commit` returns a non-terminal `refund_status`.

package/skills/search-hotels/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: search-hotels
+description: Search live hotel inventory and rates by destination, dates, and occupancy using the Jinko Travel API. Use when the user wants to find hotels, compare rates, or book a hotel.
+---
+
+# Hotel Search
+
+Search live hotel inventory using the `hotel_search` Jinko MCP tool. Returns hotels with rooms, rates, and `htl_*` offer tokens for booking.
+
+## hotel_search
+
+Live search — returns real-time availability and pricing from hotel suppliers.
+
+**Required params:**
+
+- **Destination** (provide exactly one):
+  - `query`: free-text (e.g. `"Paris"`, `"beach resort near Barcelona"`)
+  - `city_name` + optional `country_code`: structured (e.g. `"New York"` + `"us"`)
+  - `latitude` + `longitude` + optional `radius_km`: geo-radius (max 50km)
+  - `place_id`: Google Places ID
+  - `hotel_ids`: re-shop specific hotels by ID
+
+- `checkin`: check-in date (YYYY-MM-DD)
+- `checkout`: check-out date (YYYY-MM-DD)
+
+- **Occupancy** (provide one shape):
+  - Shorthand: `adults` (+ optional `children` ages array + `rooms`)
+  - Structured: `occupancies: [{ adults, children_ages? }, ...]` (one per room)
+
+**Optional params:**
+- `currency`: ISO 4217 (default USD)
+- `guest_nationality`: ISO 3166-1 alpha-2 (affects rate availability)
+- `filters`: `{ min_rating, star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results }`
+
+**Examples:**
+
+Simple city search:
+```json
+{
+  "destination": { "query": "Paris" },
+  "checkin": "2026-07-15",
+  "checkout": "2026-07-18",
+  "adults": 2
+}
+```
+
+Two rooms with kids:
+```json
+{
+  "destination": { "city_name": "Barcelona", "country_code": "es" },
+  "checkin": "2026-08-01",
+  "checkout": "2026-08-05",
+  "occupancies": [
+    { "adults": 2 },
+    { "adults": 1, "children_ages": [5, 7] }
+  ]
+}
+```
+
+4+ star hotels with pool near a POI:
+```json
+{
+  "destination": { "latitude": 41.4036, "longitude": 2.1744, "radius_km": 3 },
+  "checkin": "2026-09-10",
+  "checkout": "2026-09-12",
+  "adults": 2,
+  "filters": { "star_rating": 4, "facility_ids": ["7"] }
+}
+```
+
+**Response:** List of hotels with `hotel_id`, `name`, `address`, `star_rating`, `rating`, `review_count`, `main_photo`, and a `rooms[]` list. Each room has `rates[]` — each rate includes:
+- `offer_id`: the `htl_*` token (use as `trip_item_token` for booking)
+- `board_type` / `board_name`: meal plan (RO = Room Only, BB = Bed & Breakfast, etc.)
+- `total_amount` + `currency`: total price for the stay
+- `is_refundable` + `free_cancellation_until`
+
+## Booking flow
+
+Hotels use the same cart as flights — multi-domain trips supported:
+
+```
+hotel_search → trip(add_item, trip_item_token=<htl_* offer_id>) → trip(upsert_travelers) → book
+```
+
+The `htl_*` offer_id from any rate works directly as the `trip_item_token`. Hotels and flights can coexist in the same cart for a single Stripe checkout.
+
+See the `book-trip` skill for the full booking flow (steps 2-5 are identical for hotels and flights).
+
+## Important notes
+
+- **Dates**: YYYY-MM-DD, check-in must be today or later, check-out must be after check-in
+- **Occupancy**: use structured `occupancies[]` when room composition matters (families, groups); use shorthand `adults` for simple searches
+- **Rates expire**: offer tokens have a cache TTL (~30 min). If `trip(add_item)` fails, re-search
+- **No widget in v1**: responses are text/JSON only. Hotel widgets arrive in v1.5