fortrip 0.1.1 → 0.2.0

package/AGENT_GUIDE.md

@@ -0,0 +1,128 @@
+# Fortrip hotels
+
+Fortrip sells hotel rooms at supplier net prices. The
+`fortrip` CLI (npm package `fortrip`) calls the Fortrip API as the
+signed-in user and prints JSON.
+
+## When to use
+
+- The user wants hotels in a city, near a point, or by name, for given dates.
+- The user wants live rooms, meal plans, cancellation terms or prices for
+  specific hotels.
+- The user has picked a rate and wants to book it (you return a payment link;
+  the user pays in their browser).
+
+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
+printed this guide. The examples below shorten that to `fortrip`.
+
+When the user first asks about hotels, run `fortrip whoami` before asking
+follow-up questions, so a login can happen while they answer.
+
+If a command exits with code **3** and stderr has `loginUrl`, show it to the
+user as a link together with `userCode`, e.g. "Sign in to Fortrip: <loginUrl>
+(code BCDF-GHJK) and tell me when you're done." When they confirm, rerun the
+same command; it finishes the login itself. Don't run `fortrip login` — it
+waits for up to 10 minutes. If the rerun gives a new `loginUrl`, the old one
+expired or was denied; show the new one.
+
+If exit 3 has no `loginUrl`, the saved token was revoked: run `fortrip logout`,
+then rerun the command to get a link.
+
+In CI, the user can set `FORTRIP_TOKEN` instead. Never ask the user to paste a
+token into the chat.
+
+## Exit codes
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Success; JSON on stdout | Continue |
+| 1 | Other error (supplier error, rate no longer bookable, network) | Read `error` on stderr; re-run `rates` if a rate went stale |
+| 2 | Invalid arguments | Fix the flags; stderr `issues` lists the bad fields |
+| 3 | Not logged in | Show `loginUrl` to the user, then rerun (above) |
+| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |
+
+## Recommended order
+
+1. **Search** — find candidates and indicative prices:
+
+   ```bash
+   fortrip search --query "Bangkok" --check-in 2026-11-10 --check-out 2026-11-12 \
+     --star-min 4 --sort price-asc --page-size 10
+   ```
+
+   Use `--near lat,lng,radiusKm` for "near X", `--city-code` when known.
+   `--facility` names must match the catalogue exactly (e.g. `Swimming pool`,
+   `Parking`), otherwise nothing matches. Prices here (`price.nightlyFrom`,
+   `totalFrom`, CNY) are **indicative floors**, not quotes — say so.
+
+2. **Hotel detail** (optional) — description, policies, facilities, photos:
+
+   ```bash
+   fortrip hotel 266000 [--with-rooms]
+   ```
+
+3. **Rates** — live rooms and prices for up to 15 hotels:
+
+   ```bash
+   fortrip rates --hotel 266000 --hotel 266001 --check-in 2026-11-10 \
+     --check-out 2026-11-12 --rooms 1 --adults 2 [--child-age 6] \
+     [--nationality CN] [--board BB] [--free-cancellation]
+   ```
+
+   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).
+
+4. **Book** — only after the user picks one rate and gives guest details:
+
+   ```bash
+   fortrip book --hotel 266000 --room-id 9191658 --rate-plan "<ratePlanCode>" \
+     --check-in 2026-11-10 --check-out 2026-11-12 --rooms 1 --adults 2 \
+     --guest "John Smith" --contact-name "John Smith" \
+     --contact-phone "+8613800000000" [--contact-email john@example.com]
+   ```
+
+   `--hotel`, `--room-id`, `--rate-plan`, dates, `--rooms`, `--adults` and
+   `--child-age` must be exactly the values used in `rates`. Guest names must
+   be in Latin letters as on the passport ("First Last"; last word is the last
+   name; `"First Last:2"` puts the guest in room 2). Each room needs at least
+   one guest. `--special-requests` must be in English and isn't guaranteed.
+
+## Before giving the payment link
+
+`book` returns `paymentUrl`, `amount`, `currency`, `terms`, `statusUrl` and
+`orderUrl`. Before you hand over `paymentUrl`:
+
+1. **Show the `terms`** and get the user's confirmation: meal plan
+   (`boardCode`, `boardCount`), cancellation (`refundable`, `freeCancelUntil`,
+   the `cancellation` ladder), confirmation (`isInstantConfirm`,
+   `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 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.
+
+After paying, the user lands on `statusUrl`, which shows confirmation progress
+without signing in. `orderUrl` is the signed-in order page.
+
+## Errors from `book`
+
+- `409` with `agentOrderId`: this exact stay is already paid or completed —
+  show `orderUrl`, don't book again.
+- `409` with `changes`: price or terms changed — re-run `rates` and confirm
+  again with the user.
+- `422`: the booking was refused (guest names, too many attempts, bookings
+  paused, or a preview deployment). Read `error`.

package/README.md

@@ -53,9 +53,22 @@ Tokens don't expire; `logout` revokes them.
 
 ## Agent skill
 
-[`skills/fortrip-hotels/SKILL.md`](skills/fortrip-hotels/SKILL.md) tells an AI
-agent when to use the CLI, the call order, and what to show the user before
-handing over a payment link.
+```bash
+npx skills add FortripEngineering/fortrip-cli
+```
+
+[`skills/fortrip-hotels/SKILL.md`](skills/fortrip-hotels/SKILL.md) only tells
+the agent to run `npx -y fortrip@latest skill`, which prints
+[`AGENT_GUIDE.md`](AGENT_GUIDE.md): when to use the CLI, the call order, login,
+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
 

package/dist/cli.js

@@ -22,7 +22,10 @@ function usageError(message) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+import { readFileSync } from "fs";
+var VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
 
 // src/api.ts
 var LOGIN_HINT = "Run `npx fortrip login` first.";
@@ -96,7 +99,7 @@ function unwrap(response) {
 }
 
 // src/args.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { parseArgs } from "util";
 var BODY_OPTION = { body: { type: "string" } };
 function parse(argv, options) {
@@ -112,7 +115,7 @@ function baseBody(values) {
   let text = raw;
   if (raw.startsWith("@")) {
     try {
-      text = readFileSync(raw.slice(1), "utf8");
+      text = readFileSync2(raw.slice(1), "utf8");
     } catch (error) {
       throw usageError(`Cannot read --body file: ${error.message}`);
     }
@@ -513,6 +516,19 @@ function deviceLabel() {
   return hostname().replace(/[^\w .@-]/g, "").slice(0, 64);
 }
 
+// src/guide.ts
+import { readFile as readFile2 } from "fs/promises";
+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
 var HELP = `fortrip ${VERSION} \u2014 search, price and book Fortrip hotels
 
@@ -526,6 +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 [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
@@ -562,6 +579,11 @@ async function run(argv) {
 `);
     return void 0;
   }
+  if (command === "skill") {
+    const { positionals } = parse(rest, {});
+    process.stdout.write(await readGuide(positionals.join(" ") || void 0));
+    return void 0;
+  }
   const apiUrl = resolveApiUrl();
   const log = (line) => process.stderr.write(`${line}
 `);

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.1",
+  "version": "0.2.0",
   "description": "Search, price and book Fortrip hotels from the terminal or an AI agent.",
   "type": "module",
   "bin": {
@@ -9,6 +9,8 @@
   "files": [
     "dist",
     "skills",
+    "guides",
+    "AGENT_GUIDE.md",
     "README.md"
   ],
   "engines": {

package/skills/fortrip-hotels/SKILL.md

@@ -1,129 +1,20 @@
 ---
 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
 
-Fortrip sells hotel rooms at supplier net prices. The
-`fortrip` CLI (npm package `fortrip`) calls the Fortrip API as the
-signed-in user and prints JSON.
+Before anything else, run:
 
-## When to use
+```bash
+npx -y fortrip@latest skill
+```
 
-- The user wants hotels in a city, near a point, or by name, for given dates.
-- The user wants live rooms, meal plans, cancellation terms or prices for
-  specific hotels.
-- The user has picked a rate and wants to book it (you return a payment link;
-  the user pays in their browser).
+It prints the current instructions for the Fortrip CLI: commands, call order,
+login, and what to show the user before giving a payment link. Follow them.
+They ship with each CLI release, so this file stays short and doesn't go out
+of date.
 
-Not for flights, activities, or changing/cancelling an existing booking.
-
-## Setup
-
-Run commands with `npx -y fortrip <command>` (or `fortrip <command>`
-if installed globally).
-
-When the user first asks about hotels, run `fortrip whoami` before asking
-follow-up questions, so a login can happen while they answer.
-
-If a command exits with code **3** and stderr has `loginUrl`, show it to the
-user as a link together with `userCode`, e.g. "Sign in to Fortrip: <loginUrl>
-(code BCDF-GHJK) and tell me when you're done." When they confirm, rerun the
-same command; it finishes the login itself. Don't run `fortrip login` — it
-waits for up to 10 minutes. If the rerun gives a new `loginUrl`, the old one
-expired or was denied; show the new one.
-
-If exit 3 has no `loginUrl`, the saved token was revoked: run `fortrip logout`,
-then rerun the command to get a link.
-
-In CI, the user can set `FORTRIP_TOKEN` instead. Never ask the user to paste a
-token into the chat.
-
-## Exit codes
-
-| Code | Meaning | What to do |
-|---|---|---|
-| 0 | Success; JSON on stdout | Continue |
-| 1 | Other error (supplier error, rate no longer bookable, network) | Read `error` on stderr; re-run `rates` if a rate went stale |
-| 2 | Invalid arguments | Fix the flags; stderr `issues` lists the bad fields |
-| 3 | Not logged in | Show `loginUrl` to the user, then rerun (above) |
-| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |
-
-## Recommended order
-
-1. **Search** — find candidates and indicative prices:
-
-   ```bash
-   fortrip search --query "Bangkok" --check-in 2026-11-10 --check-out 2026-11-12 \
-     --star-min 4 --sort price-asc --page-size 10
-   ```
-
-   Use `--near lat,lng,radiusKm` for "near X", `--city-code` when known.
-   `--facility` names must match the catalogue exactly (e.g. `Swimming pool`,
-   `Parking`), otherwise nothing matches. Prices here (`price.nightlyFrom`,
-   `totalFrom`, CNY) are **indicative floors**, not quotes — say so.
-
-2. **Hotel detail** (optional) — description, policies, facilities, photos:
-
-   ```bash
-   fortrip hotel 266000 [--with-rooms]
-   ```
-
-3. **Rates** — live rooms and prices for up to 15 hotels:
-
-   ```bash
-   fortrip rates --hotel 266000 --hotel 266001 --check-in 2026-11-10 \
-     --check-out 2026-11-12 --rooms 1 --adults 2 [--child-age 6] \
-     [--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,
-   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).
-
-4. **Book** — only after the user picks one rate and gives guest details:
-
-   ```bash
-   fortrip book --hotel 266000 --room-id 9191658 --rate-plan "<ratePlanCode>" \
-     --check-in 2026-11-10 --check-out 2026-11-12 --rooms 1 --adults 2 \
-     --guest "John Smith" --contact-name "John Smith" \
-     --contact-phone "+8613800000000" [--contact-email john@example.com]
-   ```
-
-   `--hotel`, `--room-id`, `--rate-plan`, dates, `--rooms`, `--adults` and
-   `--child-age` must be exactly the values used in `rates`. Guest names must
-   be in Latin letters as on the passport ("First Last"; last word is the last
-   name; `"First Last:2"` puts the guest in room 2). Each room needs at least
-   one guest. `--special-requests` must be in English and isn't guaranteed.
-
-## Before giving the payment link
-
-`book` returns `paymentUrl`, `amount`, `currency`, `terms`, `statusUrl` and
-`orderUrl`. Before you hand over `paymentUrl`:
-
-1. **Show the `terms`** and get the user's confirmation: meal plan
-   (`boardCode`, `boardCount`), cancellation (`refundable`, `freeCancelUntil`,
-   the `cancellation` ladder), confirmation (`isInstantConfirm`,
-   `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.
-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.
-
-After paying, the user lands on `statusUrl`, which shows confirmation progress
-without signing in. `orderUrl` is the signed-in order page.
-
-## Errors from `book`
-
-- `409` with `agentOrderId`: this exact stay is already paid or completed —
-  show `orderUrl`, don't book again.
-- `409` with `changes`: price or terms changed — re-run `rates` and confirm
-  again with the user.
-- `422`: the booking was refused (guest names, too many attempts, bookings
-  paused, or a preview deployment). Read `error`.
+Needs Node.js 22 or newer. If the command fails, tell the user why instead of
+guessing the CLI's flags.