fortrip 0.1.2 → 0.2.0

package/AGENT_GUIDE.md

@@ -14,6 +14,9 @@ signed-in user and prints JSON.
 
 Not for flights, activities, or changing/cancelling an existing booking.
 
+For flexible dates, a budget, split stays, several destinations or "find me
+the best", also run `npx -y fortrip@latest skill planning` before searching.
+
 ## Setup
 
 Run every command as `npx -y fortrip@latest <command>`, the same version that
@@ -73,8 +76,8 @@ token into the chat.
      [--nationality CN] [--board BB] [--free-cancellation]
    ```
 
-   This call takes about 15 seconds. `totalPrice` is CNY at a fixed exchange
-   rate. Present each option with meal plan (`boardCode`: RO room only,
+   This call takes about 15 seconds. `totalPrice` is CNY at Stripe's exchange
+   rate (refreshed hourly). Present each option with meal plan (`boardCode`: RO room only,
    BB breakfast, HB half board, FB full board, AI all inclusive),
    `freeCancelUntil` / `refundable`, `isInstantConfirm`, and any `fees`
    (taxes paid at the hotel, in their own currency).
@@ -105,8 +108,9 @@ token into the chat.
    `confirmByMins`) and `payAtHotelFees`.
 2. **Explain the amount.** `rates` showed CNY, but the charge is `amount` in
    `currency` (usually USD), and the Stripe page may display the user's local
-   currency at Stripe's rate. The amount on the payment page is what will be
-   charged; the CNY figure was a reference.
+   currency at Stripe's rate. The CNY figure used a Stripe rate too, so it is
+   usually close, but the amount on the payment page is what will be charged;
+   the CNY figure was a reference.
 3. The link is for **this user only**: whoever has it can pay. Don't post it
    in shared channels, logs or tickets. It expires after about 3 hours 45
    minutes; call `book` again with the same details for a fresh one.

package/README.md

@@ -64,6 +64,12 @@ and what to show the user before handing over a payment link. The guide ships
 with the package, so a CLI release updates every installed skill. Edit
 `AGENT_GUIDE.md`, not `SKILL.md`.
 
+`fortrip skill planning` prints [`guides/planning.md`](guides/planning.md):
+what to ask, how to rank and how to present options for flexible dates,
+budgets, split stays and several destinations. Both guides are printed with
+`fortrip@latest` replaced by the running version, so an agent keeps using the
+same CLI for the whole conversation.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -518,8 +518,15 @@ function deviceLabel() {
 
 // src/guide.ts
 import { readFile as readFile2 } from "fs/promises";
-function readGuide() {
-  return readFile2(new URL("../AGENT_GUIDE.md", import.meta.url), "utf8");
+var GUIDES = {
+  main: "../AGENT_GUIDE.md",
+  planning: "../guides/planning.md"
+};
+async function readGuide(topic = "main") {
+  const path = GUIDES[topic];
+  if (!path) throw usageError("Usage: fortrip skill [planning]");
+  const guide = await readFile2(new URL(path, import.meta.url), "utf8");
+  return guide.replaceAll("fortrip@latest", `fortrip@${VERSION}`);
 }
 
 // src/cli.ts
@@ -535,7 +542,7 @@ Commands:
   hotel <hotelId>             Static hotel detail [--with-rooms]
   rates                       Live rooms and rates (CNY) for up to 15 hotels
   book                        Create an order and get a payment link
-  skill                       Print the guide for AI agents (Markdown)
+  skill [planning]            Print the guide for AI agents (Markdown)
 
 search:  --query <text> | --city-code <n> | --near <lat,lng,km>
          --check-in YYYY-MM-DD --check-out YYYY-MM-DD
@@ -573,8 +580,8 @@ async function run(argv) {
     return void 0;
   }
   if (command === "skill") {
-    parse(rest, {});
-    process.stdout.write(await readGuide());
+    const { positionals } = parse(rest, {});
+    process.stdout.write(await readGuide(positionals.join(" ") || void 0));
     return void 0;
   }
   const apiUrl = resolveApiUrl();

package/guides/planning.md

@@ -0,0 +1,54 @@
+# Planning a hotel stay
+
+Read this when the request is more than one hotel for fixed dates: flexible
+dates, a budget, split stays, several destinations, or "find me the best".
+Commands, login and the booking checklist are in `fortrip skill`; this covers
+what to ask, how to compare and how to present. As there, `fortrip` is short
+for `npx -y fortrip@latest`.
+
+## What to collect
+
+Keep track of: dates (or the flexible window), nights, destination(s), guests
+and rooms, room constraints (beds, connecting rooms, accessibility), budget,
+and what the user said matters most (cheapest, most flexible, closest to X).
+
+Ask only for what changes which hotels qualify or how they rank. If children
+come along, ask each child's age; `rates` and `book` need it. Don't ask for
+trip type or style: infer it from the conversation or leave it general.
+
+## Evidence
+
+- A `search` price is a floor. Never call a search result available or
+  bookable.
+- Use `hotel` only when a stated preference needs evidence (a pool, a
+  policy, room size).
+- A hotel is available only once `rates` returned a live option for it.
+- Anything the CLI didn't return, such as reviews, style, price trends or
+  exchange rates, is unknown. Say so instead of filling it in.
+
+## Ranking
+
+1. Drop options that break a hard constraint (dates, guests, budget cap,
+   required facility).
+2. Keep only options with a live rate.
+3. Order by the user's stated main goal. Goals they didn't state don't count.
+4. Use other preferences only to break ties.
+
+Use the cheapest comparable live room as the baseline unless the user fixed
+the room type. Show at most three plans, each with its price difference from
+the baseline and what it trades off (meal plan, cancellation, location,
+instant confirmation). Keep hotel names as returned and dates in the user's
+notation.
+
+For a split stay or several destinations, price each leg with its own
+`rates` call and add up the legs. Each leg is a separate `book` call and a
+separate payment link.
+
+## Stop and say so
+
+- `rates` covers up to 15 hotels per call and takes about 15 seconds. If the
+  request needs more hotels or date combinations than a few calls can cover,
+  narrow it with the user, or present the result as a comparison of the
+  hotels you priced, not the best overall.
+- Urgency is not consent: create a payment link only after the user picked a
+  rate and confirmed its terms.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fortrip",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Search, price and book Fortrip hotels from the terminal or an AI agent.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "skills",
+    "guides",
     "AGENT_GUIDE.md",
     "README.md"
   ],

package/skills/fortrip-hotels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fortrip-hotels
-description: Search hotels, compare live room rates and create a hotel booking with a payment link through Fortrip. Use when the user wants to find, price or book a hotel stay for specific dates, or asks for a hotel payment link.
+description: Search hotels, compare live room rates and create a hotel booking with a payment link through Fortrip. Use when the user wants to find, compare, price or book a hotel stay, including flexible dates, budgets, split stays or several destinations, or asks for a hotel payment link.
 ---
 
 # Fortrip hotels