@gojinko/plugin 2.28.0 → 2.29.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": "2.28.0",
+  "description": "Search flights, hotels and car rentals, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live pricing, trip management, cancellation and payment.",
+  "version": "2.29.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"
@@ -12,6 +12,8 @@
   "keywords": [
     "travel",
     "flights",
+    "hotels",
+    "car-rental",
     "booking",
     "mcp"
   ]

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": "2.28.0",
+  "description": "Search flights, hotels and car rentals, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live pricing, trip management, cancellation and payment.",
+  "version": "2.29.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"
@@ -12,6 +12,8 @@
   "keywords": [
     "travel",
     "flights",
+    "hotels",
+    "car-rental",
     "booking",
     "mcp"
   ],
@@ -19,8 +21,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Jinko Travel",
-    "shortDescription": "Flight search, booking, and trip management",
-    "longDescription": "Search flights, compare prices, book trips with ancillaries, and manage refunds using the Jinko Travel API. Supports live pricing from multiple airlines via Sabre and TravelFusion.",
+    "shortDescription": "Flight, hotel and car-rental search, booking, and trip management",
+    "longDescription": "Search flights, hotels and car rentals, compare prices, book trips with ancillaries, and manage cancellations and refunds using the Jinko Travel API. Live flight pricing from multiple airlines via Sabre and TravelFusion.",
     "developerName": "Jinko",
     "category": "Productivity",
     "capabilities": [
@@ -31,7 +33,9 @@
     "defaultPrompt": [
       "Find the cheapest flights from Paris to New York next month",
       "Book a round-trip flight from London to Tokyo",
-      "Can I get a refund on booking ORD-123?"
+      "Find a hotel near the Colosseum in Rome for three nights in May",
+      "Rent a compact car at Lyon airport for the weekend, driver aged 35",
+      "Can I get a refund on booking JNK-A7B3X9?"
     ],
     "brandColor": "#2563EB"
   }

package/README.md

@@ -1,10 +1,10 @@
 # Jinko Travel Plugin
 
-Plugin for **Claude Code** and **OpenAI Codex** that enables flight search, trip booking, and booking management via the Jinko Travel API.
+Plugin for **Claude Code** and **OpenAI Codex** that enables flight, hotel and car-rental search, trip booking, and booking management via the Jinko Travel API.
 
 ## What's included
 
-- **6 skills**: search-flights, search-hotels, book-trip, manage-booking, account, cli
+- **7 skills**: search-flights, search-hotels, search-cars, book-trip, manage-booking, account, cli
 - **MCP server config**: connects to `mcp.builders.gojinko.com`
 - **Dual-platform support**: works with both Claude Code and Codex CLI
 
@@ -40,10 +40,11 @@ codex plugin install @gojinko/plugin
 |-------|-------------|---------------|
 | `jinko:search-flights` | Find flights, explore destinations, compare prices | "Find flights from Paris to Tokyo in June" |
 | `jinko:search-hotels` | Search live hotel inventory and rates by destination, dates, and occupancy — or look up a hotel by name | "Find hotels in Tokyo for 2 nights in June" |
-| `jinko:book-trip` | Book flights, hotels, or both — travelers, ancillaries, 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:search-cars` | Search live car-rental offers by pick-up airport, place or coordinates, dates and driver | "Rent a car at Lyon airport from the 25th to the 28th" |
+| `jinko:book-trip` | Book flights, hotels, rental cars, or any mix — travelers, ancillaries, and payment | "Book the cheapest flight and pay" |
+| `jinko:manage-booking` | Refund or exchange flights, cancel hotels and car rentals | "Can I get a refund on booking JNK-A7B3X9?" |
 | `jinko:account` | Account setup guide — API keys, quotas, dashboard | "How do I set up my Jinko API key?" |
-| `jinko:cli` | Run travel ops from the terminal — search flights/hotels, build trips, book, refund, look up bookings via the `jinko` CLI | "Search flights from the terminal with the jinko CLI" |
+| `jinko:cli` | Run travel ops from the terminal — search flights/hotels/cars, build trips, book, refund, cancel, look up bookings via the `jinko` CLI | "Search flights from the terminal with the jinko CLI" |
 
 ## Authentication
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gojinko/plugin",
-  "version": "2.28.0",
-  "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight search, booking, and trip management via MCP",
+  "version": "2.29.0",
+  "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight, hotel and car-rental search, booking, and trip management via MCP",
   "private": false,
   "license": "MIT",
   "author": "Jinko <dev@gojinko.com>",

package/skills/book-trip/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: book-trip
-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.
+description: Book a trip end-to-end — flights, hotels, rental cars, or any mix 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,10 +10,10 @@ Complete booking flow using Jinko MCP tools. Each step depends on the previous
 ## Booking Flow
 
 ```
-flight_search and/or hotel_search → trip (add_item) → trip (upsert_travelers) → [trip (select_ancillaries)] → book
+flight_search and/or hotel_search and/or car_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.
+**Multi-domain carts:** Flights (`trip_item_token` from `flight_search`), hotels (`htl_*` offer_id from `hotel_search`) and rental cars (`car_*` offer_id from `car_search`) can be added to the same trip. One cart, one Stripe checkout. See the `search-hotels` and `search-cars` skills for those searches. A cart that holds a car needs `contact.title` (step 3) before checkout.
 
 ## Step 1: Get live pricing — `flight_search`
 
@@ -139,7 +139,7 @@ Returns `trip_id`. Save it for all subsequent steps.
 - `passenger_type`: `"ADULT"` (12+), `"CHILD"` (2-11), `"INFANT"` (under 2) (required)
 - `nationality`, `passport_number`, `passport_expiry`, `passport_country`: optional
 
-**Contact:** `email` is required, `phone` is optional.
+**Contact:** `email` and `phone` are required. `title` is the booking contact's honorific (`"mr"`, `"ms"`, `"mx"`, …) — **required when the cart holds a car rental**, optional otherwise; the readiness gate refuses a car cart without it before any card is charged. Free text, matched downstream against the rental provider's own title vocabulary, so keep to the common forms.
 
 ## Step 4 (optional): Add ancillaries — `trip` with `select_ancillaries`
 
@@ -194,5 +194,6 @@ Once fulfillment has been scheduled the response carries a top-level `booking_re
 - **Never skip steps** — each depends on the previous
 - **Never fabricate traveler data** — always ask the user
 - **If flight_search returns "flight_unavailable"** — do NOT proceed, show alternatives
+- **A car rental needs `contact.title`** — set it in step 3 or checkout refuses the cart
 - **Sessions expire** — if you get a 404, start over
 - **Rate limit**: 1000 requests/30 days per API key

package/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use the `jinko` CLI (npm `@gojinko/cli`) to search flights, hotels and rental cars, build trips, book, refund, cancel, 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
@@ -48,13 +48,15 @@ Prod and sandbox keys are stored separately in `~/.jinko/config.yaml`. Precedenc
 | `flight-search` | Live pricing — direct search by route + dates, or `--offer-token` price-check (returns bookable `trip_item_token`). Full shop filter set: `--max-stops`, `--departure-time-range`, `--connection-time-*-minutes`, `--refundable-only`, `--checked-bag-included`, `--via-airports`, `--origin-alternate-airports`, … |
 | `hotel-search` | Live hotel search by city/query/geo/hotel-ids |
 | `hotel-details` | Rich metadata (gallery, facilities, policies, per-room details) for a single hotel |
-| `trip` | Create / update a trip: add items, remove items, set travelers + contact |
+| `car-search` | Live car-rental offers — pick-up by `--pick-up-airport` / `--pick-up-place` / `--pick-up-geo lat,lng,range` (exactly one), branch-local `--pick-up-date-time` / `--drop-off-date-time` (no timezone), `--driver-age`, `--residence-country`. Each offer's `offer_id` (`car_*`) is the `trip_item_token`. |
+| `trip` | Create / update a trip: add items, remove items, set travelers + contact (a car rental needs `contact.title`, the honorific) |
 | `select-ancillaries` | Add baggage / seats / meals to a trip item |
 | `checkout` | Finalize a trip → returns `checkout_url` (human pays in browser) + `agent_spt_params` (agent pays programmatically). `book` is a deprecated alias. |
 | `agent-pay submit` | Pay programmatically with a Shared Payment Token (`--trip-id` + `--token`); returns the Jinko `booking_ref` once authorized; 3DS step-up falls back to `checkout_url` |
-| `trip-status` | Full status: cart, quote, fulfillment, bookings, and the Jinko `booking_ref` once fulfillment has been scheduled — it can be present before payment completes, so read `fulfillment.status` for paid (the `--booking-ref` for `get-booking` / `hotel-cancel` / `refund`) |
+| `trip-status` | Full status: cart, quote, fulfillment, bookings, and the Jinko `booking_ref` once fulfillment has been scheduled — it can be present before payment completes, so read `fulfillment.status` for paid (the `--booking-ref` for `get-booking` / `hotel-cancel` / `car-cancel` / `refund`) |
 | `get-booking` | Retrieve a booking by `JNK-*` ref + last name (guest access). Carries `calendar` — the `.ics` files for the booking's flights and stays; `--format json` carries their contents. |
 | `refund check / commit / status` | Voluntary refund flow |
+| `car-cancel preview / commit / status` | Car-rental cancellation: `preview` quotes the fee and mints the `cancellation_id` the commit is bound to; `commit` cancels (`--manual-ok` hands a `manual_required` quote to a Jinko agent, only with the customer's consent); `status` re-reads the latest attempt. No `car-exchange` exists — modifying a rental is not offered. |
 | `schema <command>` | Print request/response schema for a command |
 | `config` | Read/write CLI config |
 
@@ -109,6 +111,33 @@ 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
 ```
 
+## Car rental flow
+
+```bash
+# Search — times are BRANCH-LOCAL with no timezone; driver age + residence change the price (ask, never guess)
+jinko car-search --pick-up-airport LYS --pick-up-date-time 2026-10-25T10:00:00 \
+  --drop-off-date-time 2026-10-28T10:00:00 --driver-age 30 --residence-country FR --currency EUR
+# One-way: give the drop-off its own place
+jinko car-search --pick-up-airport LYS --pick-up-date-time 2026-10-25T10:00:00 \
+  --drop-off-airport CDG --drop-off-date-time 2026-10-28T10:00:00 --driver-age 30 --residence-country FR
+# An ambiguous --pick-up-place answers with `candidates` instead of offers: show them and retry with one
+jinko car-search --pick-up-place "Lyon Part-Dieu" …
+
+# Book: the offer_id (car_*) is the trip item token; a car cart needs the contact's honorific (title)
+jinko trip --trip-item-token car_9f3b2a17c4e8d501 \
+  --travelers '[{"first_name":"Jane","last_name":"Doe","passenger_type":"ADULT"}]' \
+  --contact '{"email":"jane@example.com","phone":"+33612345678","title":"ms"}'
+jinko checkout --trip-id tr_ABC
+
+# Cancel: preview first (quotes the fee, mints the cancellation_id), confirm with the user, then commit
+jinko get-booking --booking-ref JNK-A7B3X9 --last-name Doe          # find the car item_id
+jinko car-cancel preview --booking-ref JNK-A7B3X9 --item-id 42 --last-name Doe
+jinko car-cancel commit  --booking-ref JNK-A7B3X9 --item-id 42 --last-name Doe --cancellation-id ccl_…
+jinko car-cancel status  --booking-ref JNK-A7B3X9 --item-id 42 --last-name Doe
+```
+
+Reading a car search result: `price.pay_now` is the ONLY amount Jinko charges (`due_at_desk` is paid at the counter, `deposit` is a card hold — never sum them); `package.supplier_name` is the rental company the customer collects from; an EMPTY `cancellation_fees` list means the fee is UNKNOWN, never "free cancellation". On a cancel preview, `fee_known: false` means the same, and `manual_required: true` means a person has to complete it — `car-cancel commit --manual-ok` hands it to a Jinko agent, only once the customer has agreed. Changing a rental (dates, vehicle, extras) is not available: the options are keeping the booking or cancelling it and searching again.
+
 ## Multi-item / mixed carts
 
 `jinko trip --trip-id <existing>` reuses the existing cart. Flight + hotel in one cart ships as ONE Stripe checkout.
@@ -134,12 +163,12 @@ jinko trip --trip-id tr_ABC --remove-item-id it_123 --trip-item-token "offer_new
 
 ```bash
 # Retrieve a booking (guest access — no auth needed beyond ref + last name)
-jinko get-booking --ref JNK-A7B3X9 --last-name Doe
+jinko get-booking --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
+jinko refund check --item-id 42 --booking-ref JNK-A7B3X9 --last-name Doe
+jinko refund commit --item-id 42 --booking-ref JNK-A7B3X9 --last-name Doe
+jinko refund status --item-id 42 --booking-ref JNK-A7B3X9 --last-name Doe
 ```
 
 ## Output tips
@@ -154,12 +183,17 @@ jinko refund status --ref JNK-A7B3X9 --last-name Doe
 - **IATA codes**: `--origin PAR` uses a CITY code (matches CDG + ORY + BVA); `--origin CDG` uses an airport. `flight-search` has `--origin-type city|airport` to disambiguate — omit it and the platform classifies the code itself, which is the safest choice.
 - **Filters are requests, not guarantees**: `flight-search` answers with `applied_filters` and `unapplied_filters` (name + reason). An unapplied filter still returns 200 with offers — post-filter them yourself or tell the user the constraint could not be met. `--format table` prints the report under the results.
 - **Alternate airports widen an AIRPORT anchor**: `--origin-alternate-airports EWR LGA` adds airports beside `--origin`, never removes results, and the anchor decides ranking — so put the airport that matters most in `--origin`. Against a city anchor the list is ignored and comes back in `unapplied_filters` as `origin` / `destination`.
-- **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 `checkout` returns a quote failure, re-run `flight-search`/`hotel-search` to get a fresh token.
+- **trip_item_token format**: `offer_xxx:fare_yyy` (flight), `htl_xxx:rate_yyy` (hotel), a raw connection id (ground) or `car_xxx` (car rental) — pass every token verbatim, never truncated.
+- **Token expiry**: offers cached ~30 min (a car offer carries its own `expires_at`). If `checkout` returns a quote failure, re-run `flight-search` / `hotel-search` / `car-search` to get a fresh token.
+- **Car date-times carry no timezone**: `2026-10-25T10:00:00` is the rental desk's own local time. A `Z` or an offset is rejected rather than silently shifting the pick-up.
 - **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`
+- MCP-tool equivalents: sibling skills `search-flights`, `search-hotels`, `search-cars`, `book-trip`, `manage-booking`
 - API docs: `https://docs.gojinko.com`
 - Source: `packages/cli/src/commands/` in the `jinko-dev-tools` repo
+
+## Servicing a selected booked item
+
+Run `get-booking --booking-ref <ref>` first (guests add `--last-name`). Select the intended `items[].item_id` and inspect its `servicing` eligibility. Pass `--booking-ref` and the same `--item-id` to refund, exchange, hotel-cancel and car-cancel actions, including status polls. The ID remains stable after an exchange. Owning credentials may omit the surname; guests supply it. When a 409 `item_selection_required` lists several items, choose one from `items[]` before retrying.

package/skills/manage-booking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: manage-booking
-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.
+description: Look up bookings and manage post-booking operations (flight refunds and exchanges, hotel and car-rental cancellations) via the Jinko Travel API. Use when the user asks about booking status, refunds, cancellations, or booking modifications.
 ---
 
 # Manage Booking
@@ -25,16 +25,13 @@ Use `get_booking` to retrieve a booking by its Jinko reference and the traveler'
 - `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)
+- `items`: booked items with stable `item_id`, domain, status, per-item `servicing` eligibility and safe confirmation details (airline locator, hotel confirmation number)
 
 ## Auth model
 
-`flight_refund` supports two auth modes — pick exactly one per call:
+Call `get_booking` first and choose the booked product from `items[]`. Its numeric `item_id` remains stable after an exchange. Inspect that item's `servicing.can_refund`, `can_void`, `can_exchange`, support levels and refusal reasons before proceeding.
 
-- **Guest auth** (default for end-users): `booking_ref` + `last_name`. Works without any DevPlatform credential — the server resolves the booking via `/bookings/get`.
-- **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.
+Every refund, exchange, hotel cancellation and car-rental cancellation takes `booking_ref` plus the selected `item_id`. Guests also supply `last_name`; a credential that owns the booking may omit it. If `item_id` is omitted and several items match the requested domain, a 409 `item_selection_required` returns safe `items[]`: choose one and repeat with its ID. Carry the same selection through checks, commits and status polls.
 
 ## Refund Flow — 3 actions: `check | commit | status`
 
@@ -46,6 +43,7 @@ Always check eligibility first, then confirm with the user before committing. Us
 {
   "action": "check",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe"
 }
 ```
@@ -54,7 +52,7 @@ Always check eligibility first, then confirm with the user before committing. Us
 
 - `is_refundable`: whether a refund is possible
 - `is_automatable`: whether the refund can be processed automatically (vs. manual CS)
-- `support_level`: `"automatic"` | `"manual"` | `"unsupported"`
+- `support_level`: `"AUTO"` | `"MANUAL_REQUIRED"` | `"UNSUPPORTED"`
 - `manual_reason`: explanation if not automatable
 - `refund_amount`: estimated refund `{ value, currency, decimal_places }`
 - `penalty_amount`: cancellation fee if applicable
@@ -72,6 +70,7 @@ Only after the user confirms:
 {
   "action": "commit",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe"
 }
 ```
@@ -79,7 +78,7 @@ Only after the user confirms:
 **Response includes:**
 
 - `refund_status`: `"refunded"` | `"processing"` | `"failed"` | ...
-- `confirmed_refund_amount`: actual refunded `{ value, currency, decimal_places }` (when available)
+- `refund_amount`: customer refund `{ value, currency, decimal_places }` (when available); `confirmed_refund_amount` is a deprecated supplier figure
 - `refund_reference`: opaque reference string — persist this to poll with `status`
 - `warnings`: any post-commit caveats
 
@@ -91,6 +90,7 @@ If `refund_status` is not a terminal state, follow up with `status`.
 {
   "action": "status",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe",
   "refund_reference": "<from commit response>"
 }
@@ -109,9 +109,9 @@ If `refund_status` is not a terminal state, follow up with `status`.
 | 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`). |
+| `booking_ref` | string | Required. 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. |
+| `item_id` | positive integer | Stable booked item ID from `get_booking`. Required when several products of this domain exist. |
 | `ticket_numbers` | string[] | Optional. Scope refund to specific tickets. |
 | `provider` | string | Optional. Override provider hint. |
 | `refund_reference` | string | For `status` only. Returned by `commit`. |
@@ -126,6 +126,7 @@ Use `flight_exchange` to change flights on an existing booking. Always shop firs
 {
   "action": "shop",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe",
   "preferred_departure_date": "2026-06-15"
 }
@@ -133,7 +134,7 @@ Use `flight_exchange` to change flights on an existing booking. Always shop firs
 
 **Response includes:**
 
-- `support_level`: `"automatic"` | `"manual"` | `"unsupported"`
+- `support_level`: `"AUTO"` | `"MANUAL_REQUIRED"` | `"UNSUPPORTED"`
 - `offers`: array of `{ offer_id, description, metadata }` — alternative flights
 - `warnings`: any caveats to surface to the user
 
@@ -145,6 +146,7 @@ Use `flight_exchange` to change flights on an existing booking. Always shop firs
 {
   "action": "price",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe",
   "offer_id": "<from shop response>"
 }
@@ -171,6 +173,7 @@ Only after the user confirms:
 {
   "action": "commit",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe",
   "offer_id": "<from shop response>",
   "session_reference": "<from price response>"
@@ -181,7 +184,7 @@ Only after the user confirms:
 
 - `status`: `"CONFIRMED"` | `"PENDING"` | `"PARTIAL_FAILURE"`
 - `exchange_reference`: opaque reference for status polling
-- `new_order_id`: new order ID if exchange created a new booking
+- `airline_locator`: airline record locator for the current itinerary; keep servicing with the same Jinko reference and booked item ID
 - `new_ticket_numbers`: new ticket numbers issued
 - `original_ticket_status`: status of the original tickets
 - `payment_outcome`: final payment action taken
@@ -195,6 +198,7 @@ If `status` is not `CONFIRMED`, follow up with `status`.
 {
   "action": "status",
   "booking_ref": "JNK-ZNBGTP",
+  "item_id": 42,
   "last_name": "Doe"
 }
 ```
@@ -211,23 +215,121 @@ If `status` is not `CONFIRMED`, follow up with `status`.
 | 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`). |
+| `booking_ref` | string | Required. 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. |
+| `item_id` | positive integer | Stable booked item ID from `get_booking`. Required when several products of this domain exist. |
 | `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. |
 
+## Car Rental Cancellation — `car_cancel`: `preview | commit | status`
+
+Cancel a car rental booked through Jinko and refund the payment less the cancellation fee. The fee in force is quoted first and persisted, so the cancellation is bound to the terms the customer saw. **Changing a rental — dates, vehicle, upgrade, extras — is not available.** If the user asks for a modification, say so plainly: the options are keeping the booking as is, or cancelling it (fee shown first) and booking a new rental with `car_search` (see the `search-cars` skill). There is no `car_exchange` tool.
+
+### Step 1: Quote the fee — `car_cancel` with `action: "preview"`
+
+```json
+{
+  "action": "preview",
+  "booking_ref": "JNK-8PT9VS",
+  "item_id": 42,
+  "last_name": "Carrard"
+}
+```
+
+Nothing is cancelled. The result is a top-level `status` (`success` here; `not_found` for a wrong booking_ref + last_name pair, which never says which half was wrong; `item_selection_required` with `items[]` when several cars match) with the quote under `data`. **`data` includes:**
+
+- `cancellation_id`: the `ccl_…` reference — **required for `commit`**, it binds the commit to this quote
+- `cancellable`: whether the rental can be cancelled as it stands
+- `fee_known`: **`false` means the fee could NOT be established — UNKNOWN, not free.** `fee` and `refund_amount` are then absent, not zero. Say "we will confirm the cancellation fee".
+- `fee`, `paid`, `refund_amount` (paid minus fee; absent is not zero), `non_refundable`
+- `manual_required`: `true` means this cancellation cannot be completed online (fee unknown, rental changed after payment, fee in another currency or above the rental) — `refund_review_reason` says which, and no refund figure may be quoted. See "when a person has to complete it".
+- `refund_pending_review` + `refund_review_reason`: the refund needs a person before it is issued
+- `expires_at`: the quote is committable until then; preview again after it
+
+**Present the fee and the refund clearly and get explicit confirmation before committing.** This ends the rental.
+
+### Step 2: Cancel — `car_cancel` with `action: "commit"`
+
+Only after the user confirms:
+
+```json
+{
+  "action": "commit",
+  "booking_ref": "JNK-8PT9VS",
+  "item_id": 42,
+  "last_name": "Carrard",
+  "cancellation_id": "ccl_2f7c9a4e8b1d4c6f9e3a5b7d1c2e4f6a",
+  "reason": "Change of plans"
+}
+```
+
+Safe to repeat: a committed cancellation is reported as it stands rather than cancelled twice. On `status: "success"`, **`data` includes:**
+
+- `state`: `confirmed` (cancelled, refund issued or on its way) · `pending` (recorded but not finished — the platform or a Jinko agent still has it; follow with `status`, do not commit again) · `rejected` (the supplier declined, the booking still stands — surface `rejected_reason`; an outcome, not an error) · `failed` (read `status` before trying again)
+- `fee_known`, `fee`, `paid`, `refund_amount`
+- `refund_pending_review`: `true` means the booking IS cancelled (or recorded for an agent) but the refund needs a person — do not quote `refund_amount` as final
+- `completed_at`
+
+**A commit can be refused without anything happening.** The refusal is the result's top-level `status`, with the platform's own code in `conflict_code`: `quote_expired` (preview again) · `quote_drift` (the refund moved since the preview — `requote` is a fresh `ccl_…` reference and `current_refund` the figure now; show it, then commit with `cancellation_id: <requote>`) · `not_allowed` (the rental can no longer be cancelled as it stands — `error` says why; `action: "status"` reports what stands) · `conflict` with `conflict_code: "active_operation_exists"` (`active_operation` names the cancellation already running — wait, then poll `status`) or `conflict_code: "funds_unavailable"` (`shortfall` is what the original payment cannot cover yet) · `manual_required` (see below). None of these means the booking reference or last name is wrong — that answers `status: "not_found"`.
+
+### When a person has to complete it — `manual_ok`
+
+A preview with `cancellable: false` and `manual_required: true` is not a dead end. If — and only if — the customer explicitly agrees to hand the cancellation to a Jinko agent, commit with the same `cancellation_id` and `manual_ok: true`:
+
+```json
+{
+  "action": "commit",
+  "booking_ref": "JNK-8PT9VS",
+  "item_id": 42,
+  "last_name": "Carrard",
+  "cancellation_id": "ccl_2f7c9a4e8b1d4c6f9e3a5b7d1c2e4f6a",
+  "manual_ok": true
+}
+```
+
+The cancellation is then recorded for the agent (`state: "pending"`, `refund_pending_review: true`); nothing is sent to the rental company by that call, and the agent completes it and settles the refund by hand. **Never send `manual_ok` pre-emptively** — it is the customer's consent, not a retry flag. On a preview that can be committed online it changes nothing.
+
+### Step 3: Poll — `car_cancel` with `action: "status"`
+
+```json
+{
+  "action": "status",
+  "booking_ref": "JNK-8PT9VS",
+  "item_id": 42,
+  "last_name": "Carrard"
+}
+```
+
+Read-only; polling can never start a cancellation. A booking with no cancellation on record answers `status: "no_attempt"` — run `preview` first.
+
+### Car Cancel Schema
+
+| Field | Type | Purpose |
+|---|---|---|
+| `action` | `"preview"` \| `"commit"` \| `"status"` | Required. Which step of the flow. |
+| `booking_ref` | string | Required. Jinko booking reference (e.g. `JNK-8PT9VS`). |
+| `item_id` | positive integer | Stable booked item ID from `get_booking`. Required when several cars are on the booking. |
+| `last_name` | string | Guest auth — the driver's surname. An owning credential may omit it. |
+| `cancellation_id` | string | For `commit`. The `ccl_…` reference from `preview`. |
+| `reason` | string | For `commit` only. Optional free text, carried into the cancellation email. |
+| `manual_ok` | boolean | For `commit` only. `true` hands a `manual_required` preview to a Jinko agent — only with the customer's explicit agreement. |
+
+Money on every step is `{ value, currency, decimal_places, display? }` in minor units — divide by `10^decimal_places`, or print `display`.
+
 ## Important rules
 
 - **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.
+- **Keep the selected item** — use the same `booking_ref` and stable `item_id` throughout servicing, including after an exchange.
 - **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`.
+- **Always preview before committing a car cancellation** — the `cancellation_id` binds the commit to the quoted fee, and the preview is where the customer sees the fee.
+- **An unknown car cancellation fee is not a free one** — `fee_known: false` or an absent fee means "we will confirm the fee", never "free".
+- **Car rentals cannot be modified** — never promise a date change, an upgrade or a different vehicle; offer cancel-and-rebook, and send `manual_ok` only with the customer's explicit consent.

package/skills/search-cars/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: search-cars
+description: Search live car-rental availability by pick-up airport, place or coordinates, a date-time window and the driver's age and residence, using the Jinko Travel API. Use when the user wants to rent or hire a car, compare rental offers, or book a car.
+---
+
+# Car Rental Search
+
+Search live car-rental inventory with the `car_search` Jinko MCP tool. Returns priced, bookable offers whose `offer_id` (`car_*`) is a trip item token — booking rides the shared cart, exactly like a flight or a hotel. There is **no car-specific booking tool**, and there is **no car exchange**: changing a rental's dates, vehicle or extras is not available — the options are keeping the booking or cancelling it (`car_cancel`, in the `manage-booking` skill) and searching again.
+
+## car_search
+
+Live search — each call reaches the rental supplier.
+
+**Required params:**
+
+- `pick_up`: where and when the car is collected
+  - `date_time`: **branch-local, zone-less** `"YYYY-MM-DDTHH:MM:SS"` (e.g. `"2026-10-25T10:00:00"`). A `Z` or a UTC offset is rejected — the rental desk works in its own local time.
+  - **exactly one** place shape:
+    - `airport_code`: 3-letter IATA (e.g. `"LYS"`). Prefer it whenever the user named an airport — it needs no resolution step.
+    - `place`: free text (`"lyon part dieu"`, `"Lyon city centre"`), resolved server-side. When it matches several genuinely different rental locations the response carries `candidates` **instead of** offers.
+    - `geo`: `{ latitude, longitude, range }` for "near me" (range in metres, minimum 50). **Round-trip only.**
+- A drop-off time, one of:
+  - `drop_off_date_time`: branch-local return time — round trip, the car goes back to the pick-up branch.
+  - `drop_off`: `{ date_time, airport_code | place | geo }` — a **one-way** rental returned somewhere else.
+- `driver_age`: 18–99. **Price-affecting — ask the user, never guess.**
+- `residence_country`: ISO 3166-1 alpha-2 (e.g. `"FR"`). **Price-affecting**, and decides which suppliers will rent at all.
+
+**Optional params:**
+
+- `currency`: ISO 4217 display currency (default USD)
+- `lang`: BCP-47 tag for provider text (package names, fuel policy), e.g. `"en-gb"`
+
+Provider ids (location, city, branch, supplier) are never accepted on this surface.
+
+**Examples:**
+
+Round trip from an airport:
+```json
+{
+  "pick_up": { "airport_code": "LYS", "date_time": "2026-10-25T10:00:00" },
+  "drop_off_date_time": "2026-10-28T10:00:00",
+  "driver_age": 30,
+  "residence_country": "FR",
+  "currency": "EUR"
+}
+```
+
+One-way, free-text pick-up:
+```json
+{
+  "pick_up": { "place": "Lyon Part-Dieu", "date_time": "2026-10-25T10:00:00" },
+  "drop_off": { "airport_code": "CDG", "date_time": "2026-10-28T18:00:00" },
+  "driver_age": 42,
+  "residence_country": "GB"
+}
+```
+
+**Response:** a top-level `status` — `success`, `ambiguous_place` (candidates instead of offers, see below), `no_results` or `error` — with the result under `data`. `data.offers[]` flattens one vehicle × rate package × branch pair per entry:
+
+- `offer_id`: the `car_*` trip item token — pass it **verbatim** to `trip(add_item)`
+- `expires_at`: about 30 minutes — search again after it
+- `on_request`: the supplier confirms by hand, so the booking settles asynchronously
+- `vehicle`: `name` (the model, "or similar" unless `model_guaranteed`), `acriss_code`, `category`, `transmission`, `fuel_type`, `seats`, `doors`, suitcase counts, `air_conditioned`, `images[]`
+- `package`: `name` (the rate plan), **`supplier_name` (the rental company the customer physically collects the car from — Avis, Hertz, Europcar, Sixt — show it with every offer)**, `fuel_policy`, `mileage_unlimited` / `mileage_allowance`, `inclusions`, `coverages`, `fees`
+- `pick_up` / `drop_off`: the branch — `name`, `address`, `city`, `country`, `phone`, `date_time` (branch-local), `time_zone` (IANA — the only way to turn a local time into an instant), `opening_hours`, `out_of_hours`, `requires_flight_number`, `terminals`, `is_meet_and_greet`
+- `price`: see money below
+- `cancellation_fees[]`: `{ type, fee, non_refundable, applicable_from, applicable_to, applicable_now }`
+- `driver_age_range`: `{ min, max }`
+
+Plus `data.resolved_place` (what an unambiguous free-text place matched), `data.currency`, `data.warnings`, and the truncation counters `data.total_found` / `data.offers_shown` / `data.offers_omitted`: when `offers_omitted` is above zero, `data.notice` says so — **narrow the search** (dates, place, a smaller radius) rather than treating the list as complete; there is no paging.
+
+### Ambiguous place — `candidates`
+
+When `place` is ambiguous the response is `status: "ambiguous_place"` with `data.candidates[]` (`{ name, kind, city, country }`) and **no offers**. That is a retry signal, not an empty result: put the candidates to the user and search again with the chosen candidate's `name` as `place` (qualify it with the city — "City Centre, Lyon" — when two share a name). **Never auto-pick a candidate**: "Lyon" is an airport, a rail station and a downtown office that book three different counters.
+
+## Reading the money
+
+- `price.pay_now` is the **only** amount Jinko charges at checkout.
+- `price.due_at_desk` is collected by the rental desk in local currency — display only.
+- `price.deposit` is a card hold; `price.estimated_total` is the supplier's FX-movable estimate.
+- **Never sum them into a total.**
+- Amounts are `{ value, currency, decimal_places, display? }` — `value` is an integer in minor units; divide by `10^decimal_places`, or print `display` as sent.
+- **An empty `cancellation_fees` list means the supplier published no schedule: the fee is UNKNOWN. Never present that as free cancellation.** A coverage's `excess` of `null` means "not stated", not "no excess".
+
+## Booking flow
+
+Cars use the same cart as flights and hotels:
+
+```
+car_search → trip(add_item, trip_item_token=<car_* offer_id>) → trip(upsert_travelers, contact.title!) → book
+```
+
+Two things differ from a flight or hotel booking:
+
+- **`contact.title` is required.** The booking contact's honorific (`"mr"`, `"ms"`, `"mx"`, …) goes in `upsert_travelers.contact.title`. The readiness gate refuses a car cart without it, before any card is charged. It is matched against the rental provider's own title vocabulary, so keep to the common forms.
+- **`driver_age` is baked into the rate** and is never asked again at booking.
+
+See the `book-trip` skill for steps 2–5; they are otherwise identical. To cancel a booked rental, use `car_cancel` in the `manage-booking` skill.
+
+## Important notes
+
+- **Date-times**: `YYYY-MM-DDTHH:MM:SS`, branch-local, no timezone; drop-off must be after pick-up.
+- **Places**: exactly one of `airport_code`, `place`, `geo` per end; `geo` is round-trip only.
+- **Offers expire** (`expires_at`): if `trip(add_item)` fails, search again.
+- **`requires_flight_number` on a branch** is the supplier's policy and cannot be satisfied today (Jinko carries no flight number): `"always"` means that branch cannot be booked at all — prefer an offer from another branch.
+- **No modifications.** Do not promise a date change, an upgrade or a different vehicle on an existing rental; offer to cancel (fee shown first) and book again.