itamatrix 1.0.2 → 1.1.0

package/dist/browser/batch.js

@@ -11,6 +11,17 @@ export function extractSearchPayload(batchBody) {
     }
     return null;
 }
+/**
+ * The itinerary-detail page issues its own `/batch` whose part carries a
+ * `bookingDetails` body (priced solution: fare construction, taxes, segments).
+ */
+export function extractBookingDetailsPayload(batchBody) {
+    for (const obj of jsonObjects(batchBody)) {
+        if (obj && typeof obj === "object" && "bookingDetails" in obj)
+            return obj;
+    }
+    return null;
+}
 /**
  * Keys the price-calendar ("lowest fare") response is expected to carry. The
  * exact shape is unconfirmed (no captured fixture yet — DESIGN P3); this matches
@@ -35,6 +46,7 @@ export function extractCalendarPayload(batchBody) {
     }
     return null;
 }
+/** True if `obj` carries any of the known price-calendar summary keys. */
 function hasCalendarKey(obj) {
     return CALENDAR_KEYS.some((k) => k in obj);
 }

package/dist/browser/forms.js

@@ -24,7 +24,7 @@ export async function driveSearchForm(page, spec) {
  * `solutionList` shape as a normal search (N slices instead of 1–2).
  */
 export async function driveMultiCityForm(page, spec) {
-    await page.getByRole("tab", { name: "Multi-City", exact: true }).click();
+    await page.getByRole("tab", { name: /multi[\s-]?city/i }).click();
     await ensureLegRows(page, spec.slices.length);
     for (const [i, leg] of spec.slices.entries()) {
         await fillAirport(page, 2 * i, leg.origin);
@@ -87,13 +87,16 @@ async function setAdvancedControls(page, spec, roundTrip) {
     }
 }
 /**
- * Adds "Add another flight" rows until the form has `count` legs. Matrix shows
- * two legs by default, so we only click for the extras.
+ * Adds "Add Flight" rows until the form has `count` legs. The default number of
+ * rows Matrix renders has drifted (currently one), so derive it from the live
+ * combobox count (two per leg) rather than assuming a fixed starting point.
  */
 async function ensureLegRows(page, count) {
     const addLeg = page.getByRole("button", { name: /add (another )?flight/i });
-    for (let existing = 2; existing < count; existing++) {
+    const comboboxes = page.getByRole("combobox", { name: "Add airport" });
+    for (let existing = (await comboboxes.count()) / 2; existing < count; existing++) {
         await addLeg.click();
+        await comboboxes.nth(2 * existing + 1).waitFor({ state: "visible", timeout: 15_000 });
     }
 }
 /** Multi-city: shared cabin/stops globally, routing/ext per leg by row index. */

package/dist/browser/session.js

@@ -1,7 +1,7 @@
 import { chromium } from "playwright";
 import { driveCalendarForm, driveMultiCityForm, driveSearchForm } from "./forms.js";
-import { extractCalendarPayload, extractSearchPayload } from "./batch.js";
-import { parseCalendarResponse, parseSearchResponse, } from "../model/types.js";
+import { extractBookingDetailsPayload, extractCalendarPayload, extractSearchPayload, } from "./batch.js";
+import { parseBookingDetails, parseCalendarResponse, parseSearchResponse, } from "../model/types.js";
 const SEARCH_URL = "https://matrix.itasoftware.com/search";
 // Results arrive in a multipart `/batch` response (not the documented
 // `/v1/search`); the relevant part carries a `solutionList` JSON body.
@@ -28,6 +28,14 @@ export async function runMultiCity(spec, opts = {}) {
 export async function runCalendar(spec, opts = {}) {
     return runDriver((page) => driveCalendarForm(page, spec), extractCalendarPayload, parseCalendarResponse, opts);
 }
+/** Like {@link runSearch}, then opens the top result's detail page for its fare construction + Google Flights link. */
+export function runSearchWithDetails(spec, opts = {}) {
+    return runDriverWithDetails((page) => driveSearchForm(page, spec), opts);
+}
+/** Multi-city counterpart of {@link runSearchWithDetails}. */
+export function runMultiCityWithDetails(spec, opts = {}) {
+    return runDriverWithDetails((page) => driveMultiCityForm(page, spec), opts);
+}
 /**
  * Shared driver: launch Chromium, drive the form, intercept the first `/batch`
  * response that `match` accepts, and parse it. All P1–P3 commands share this;
@@ -61,6 +69,88 @@ async function runDriver(drive, match, parse, opts) {
         await browser.close();
     }
 }
+/**
+ * Search, then drill into the top result's detail page. The detail capture is
+ * best-effort: if the row can't be opened or the `bookingDetails` part never
+ * arrives, `details` is null and the search results are still returned. Reuses
+ * the same browser/page so the detail page inherits the live solution session.
+ */
+async function runDriverWithDetails(drive, opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const browser = await launch(opts.headful ?? false);
+    const page = await newStealthPage(browser);
+    const waiter = waitForResponse(page, extractSearchPayload, timeoutMs);
+    waiter.promise.catch(() => { });
+    try {
+        try {
+            await page.goto(SEARCH_URL, { waitUntil: "domcontentloaded", timeout: 60_000 });
+            await drive(page);
+        }
+        catch {
+            throw new Error("Failed to drive the Matrix search form (the site may have changed). Run with --headful to debug.");
+        }
+        const search = parseSearchResponse(await waiter.promise);
+        waiter.cancel();
+        const details = await captureTopDetails(page, timeoutMs);
+        return { search, details };
+    }
+    finally {
+        waiter.cancel();
+        await browser.close();
+    }
+}
+/**
+ * Opens the first results row and waits for its `bookingDetails` part, then reads
+ * the "Open in Google Flights" link from the DOM (it's rendered client-side, not
+ * in the API). Returns null on any failure — detail is an enrichment, never fatal.
+ */
+async function captureTopDetails(page, timeoutMs) {
+    const waiter = waitForResponse(page, extractBookingDetailsPayload, timeoutMs);
+    waiter.promise.catch(() => { });
+    try {
+        if (!(await openFirstSolution(page)))
+            return null;
+        const bookingDetails = parseBookingDetails(await waiter.promise);
+        return { bookingDetails, googleFlightsUrl: await readGoogleFlightsUrl(page) };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        waiter.cancel();
+    }
+}
+/** Clicks into the first itinerary; true if a clickable row was found. */
+async function openFirstSolution(page) {
+    const candidates = [
+        page.getByRole("link").filter({ hasText: /\$|USD|\d:\d/ }).first(),
+        page.locator("td a, .mat-row a, [role=row] a").first(),
+        page.locator("[role=row]").filter({ hasText: /\$|USD/ }).nth(1),
+    ];
+    for (const candidate of candidates) {
+        try {
+            // click() auto-waits for the element; no count() pre-check, which would
+            // skip a row that renders a moment later.
+            await candidate.click({ timeout: 8_000 });
+            return true;
+        }
+        catch {
+            // Try the next selector; the results DOM has drifted before.
+        }
+    }
+    return false;
+}
+/** Reads the detail page's "Open in Google Flights" href; undefined if absent. */
+async function readGoogleFlightsUrl(page) {
+    const link = page.getByRole("link", { name: /google flights/i }).first();
+    try {
+        return (await link.getAttribute("href", { timeout: 8_000 })) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Launches Chromium, mapping Playwright's path-leaking errors to safe messages. */
 async function launch(headful) {
     try {
         return await chromium.launch({
@@ -78,6 +168,7 @@ async function launch(headful) {
         throw new Error("Failed to launch the browser. Run with --headful to debug, or reinstall Chromium: npx playwright install chromium");
     }
 }
+/** New page with a real Chrome UA and `navigator.webdriver` hidden (light stealth). */
 async function newStealthPage(browser) {
     const context = await browser.newContext({
         userAgent: STEALTH_UA,

package/dist/cli.js

@@ -65,6 +65,7 @@ program
     .option("--carriers <list>", "comma-separated carriers, e.g. UA,AA (sugar for --routing)")
     .option("--routing <codes>", "ITA routing codes (path) — see docs/ROUTING_CODES.md")
     .option("--ext <codes>", "ITA extension codes (faring/filters) — see docs/ROUTING_CODES.md")
+    .option("--details", "also fetch the top result's fare construction + Google Flights link (live, skips cache)")
     .option("--headful", "show the browser window (debug)")
     .action(async (origin, dest, cmdOpts, command) => {
     const globals = command.parent.opts();
@@ -80,6 +81,7 @@ program
         carriers: cmdOpts.carriers,
         routing: cmdOpts.routing,
         ext: cmdOpts.ext,
+        details: cmdOpts.details,
         headful: cmdOpts.headful,
         format: resolveFormat(globals.json, globals.table),
         cache: globals.cache,
@@ -99,6 +101,7 @@ program
     .option("--carriers <list>", "comma-separated carriers, e.g. UA,AA (sugar for --routing)")
     .option("--routing <codes>", "ITA routing codes applied to every leg")
     .option("--ext <codes>", "ITA extension codes applied to every leg")
+    .option("--details", "also fetch the top result's fare construction + Google Flights link (live, skips cache)")
     .option("--headful", "show the browser window (debug)")
     .action(async (cmdOpts, command) => {
     const globals = command.parent.opts();
@@ -112,6 +115,7 @@ program
         routing: cmdOpts.routing ?? carriersToRouting(cmdOpts.carriers),
         ext: cmdOpts.ext,
         format: resolveFormat(globals.json, globals.table),
+        details: cmdOpts.details,
         headful: cmdOpts.headful,
         cache: globals.cache,
         cacheTtlMinutes: globals.cacheTtl,

package/dist/commands/multicity.js

@@ -1,9 +1,10 @@
-import { runMultiCity } from "../browser/session.js";
+import { runMultiCity, runMultiCityWithDetails } from "../browser/session.js";
 import { withCache } from "../cache.js";
 import { normalize } from "../render/normalize.js";
 import { renderJson } from "../render/json.js";
 import { renderTable } from "../render/table.js";
-import { requireIsoDate, requirePageLimit, resolveCacheOptions, validateTripControls, } from "./shared.js";
+import { requireIsoDate, requirePageLimit, resolveCacheOptions, toItineraryDetails, validateTripControls, } from "./shared.js";
+/** Parses/validates legs, runs the multi-city search, and renders table or JSON. */
 export async function runMultiCityCommand(opts) {
     const slices = parseLegs(opts);
     validateTripControls(opts);
@@ -16,10 +17,21 @@ export async function runMultiCityCommand(opts) {
         stops: opts.stops,
         extraStops: opts.extraStops,
     };
-    const response = await withCache("multicity", spec, resolveCacheOptions(opts), () => runMultiCity(spec, { headful: opts.headful }));
-    const result = normalize(response, opts.limit);
+    const result = await multicity(spec, opts);
     return opts.format === "json" ? renderJson(result) : renderTable(result);
 }
+/** `--details` drills into the top result live, so it bypasses the cache (see search.ts). */
+async function multicity(spec, opts) {
+    if (opts.details) {
+        const { search: response, details } = await runMultiCityWithDetails(spec, {
+            headful: opts.headful,
+        });
+        const result = normalize(response, opts.limit);
+        return details ? { ...result, details: toItineraryDetails(details) } : result;
+    }
+    const response = await withCache("multicity", spec, resolveCacheOptions(opts), () => runMultiCity(spec, { headful: opts.headful }));
+    return normalize(response, opts.limit);
+}
 /** Parses `--leg ORIGIN:DEST:DATE` flags into slices; `--routing`/`--ext` apply to all. */
 export function parseLegs(opts) {
     if (!opts.legs || opts.legs.length < 2) {
@@ -27,6 +39,7 @@ export function parseLegs(opts) {
     }
     return opts.legs.map((raw, i) => toSlice(raw, i, opts));
 }
+/** Parses one `ORIGIN:DEST:DATE` leg, applying shared routing/ext, into a Slice. */
 function toSlice(raw, index, opts) {
     const parts = raw.split(":");
     if (parts.length !== 3) {

package/dist/commands/search.js

@@ -1,9 +1,10 @@
-import { runSearch } from "../browser/session.js";
+import { runSearch, runSearchWithDetails } from "../browser/session.js";
 import { withCache } from "../cache.js";
 import { normalize } from "../render/normalize.js";
 import { renderJson } from "../render/json.js";
 import { renderTable } from "../render/table.js";
-import { carriersToRouting, requireIsoDate, requirePageLimit, resolveCacheOptions, validateTripControls, } from "./shared.js";
+import { carriersToRouting, requireIsoDate, requirePageLimit, resolveCacheOptions, toItineraryDetails, validateTripControls, } from "./shared.js";
+/** Validates input, runs a one-way/round-trip search, and renders table or JSON. */
 export async function runSearchCommand(origin, dest, opts) {
     validate(origin, dest, opts);
     const spec = {
@@ -19,14 +20,30 @@ export async function runSearchCommand(origin, dest, opts) {
         routing: resolveRouting(opts),
         ext: opts.ext,
     };
-    const response = await withCache("search", spec, resolveCacheOptions(opts), () => runSearch(spec, { headful: opts.headful }));
-    const result = normalize(response, opts.limit);
+    const result = await search(spec, opts);
     return opts.format === "json" ? renderJson(result) : renderTable(result);
 }
+/**
+ * `--details` needs a live browser session (it drills into the detail page using
+ * the in-flight solution session), so it bypasses the cache; the plain path stays
+ * cached.
+ */
+async function search(spec, opts) {
+    if (opts.details) {
+        const { search: response, details } = await runSearchWithDetails(spec, {
+            headful: opts.headful,
+        });
+        const result = normalize(response, opts.limit);
+        return details ? { ...result, details: toItineraryDetails(details) } : result;
+    }
+    const response = await withCache("search", spec, resolveCacheOptions(opts), () => runSearch(spec, { headful: opts.headful }));
+    return normalize(response, opts.limit);
+}
 /** `--routing` wins; otherwise `--carriers UA,AA` becomes the routing `UA,AA+`. */
 export function resolveRouting(opts) {
     return opts.routing ?? carriersToRouting(opts.carriers);
 }
+/** Throws on bad origin/dest, dates, return-before-depart, or trip-control values. */
 function validate(origin, dest, opts) {
     if (!origin || !dest)
         throw new Error("origin and destination are required");

package/dist/commands/shared.js

@@ -1,4 +1,5 @@
 import { CABIN_LABELS, STOPS_LABELS, } from "../model/spec.js";
+import { collectFareConstruction } from "../model/types.js";
 import { DEFAULT_CACHE_TTL_MINUTES } from "../cache.js";
 export function resolveCacheOptions(opts) {
     const minutes = opts.cacheTtlMinutes ?? DEFAULT_CACHE_TTL_MINUTES;
@@ -61,6 +62,13 @@ export function carriersToRouting(carriers) {
         return undefined;
     return codes.length === 1 ? `${codes[0]}+` : `(${codes.join(",")})+`;
 }
+/** Shapes a browser-captured top-result detail into the flat render view. */
+export function toItineraryDetails(capture) {
+    return {
+        fareConstruction: collectFareConstruction(capture.bookingDetails),
+        googleFlightsUrl: capture.googleFlightsUrl,
+    };
+}
 export function requireIsoDate(value, flag) {
     if (!DATE_RE.test(value) || !isRealCalendarDate(value)) {
         throw new Error(`${flag} must be a valid date (YYYY-MM-DD), got "${value}"`);

package/dist/model/types.js

@@ -92,6 +92,44 @@ export function parseCalendarResponse(raw) {
     }
     return root;
 }
+export function parseBookingDetails(raw) {
+    const root = unwrapResponse(raw);
+    if (!root || typeof root !== "object" || Array.isArray(root) || !("bookingDetails" in root)) {
+        throw new Error("Itinerary-detail response did not contain bookingDetails");
+    }
+    return root;
+}
+/** Deep-scan for every `fareCalculations[].lines` string, deduped, in order. */
+export function collectFareConstruction(node) {
+    const lines = [];
+    const walk = (o) => {
+        if (Array.isArray(o)) {
+            o.forEach(walk);
+            return;
+        }
+        if (!o || typeof o !== "object")
+            return;
+        for (const [key, value] of Object.entries(o)) {
+            if (key === "fareCalculations")
+                collectLines(value, lines);
+            walk(value);
+        }
+    };
+    walk(node);
+    return [...new Set(lines)];
+}
+/** Appends every string in `calculations[].lines` to `out`. */
+function collectLines(calculations, out) {
+    if (!Array.isArray(calculations))
+        return;
+    for (const calc of calculations) {
+        const calcLines = calc?.lines;
+        if (Array.isArray(calcLines)) {
+            out.push(...calcLines.filter((v) => typeof v === "string"));
+        }
+    }
+}
+/** Unwraps the `{ response: … }` envelope Matrix bodies are sometimes wrapped in. */
 function unwrapResponse(raw) {
     return raw && typeof raw === "object" && "response" in raw
         ? raw.response

package/dist/render/normalize.js

@@ -5,6 +5,7 @@
 function parseCarrier(flight) {
     return flight?.match(/^[A-Z0-9]{2}/)?.[0];
 }
+/** Flattens one Matrix solution into the agent-friendly {@link FlatSolution} view. */
 function flattenSolution(sol) {
     const slices = sol.itinerary.slices.map((s) => ({
         origin: s.origin.code,

package/dist/render/table.js

@@ -7,6 +7,7 @@ function fmtTime(iso) {
         return iso;
     return `${m[2]}-${m[3]} ${m[4]}`;
 }
+/** Formats minutes as `6h30`; empty string when undefined. */
 function fmtDuration(min) {
     if (min == null)
         return "";
@@ -14,6 +15,7 @@ function fmtDuration(min) {
     const m = min % 60;
     return `${h}h${String(m).padStart(2, "0")}`;
 }
+/** One line per slice: route, times, stops/duration, flight numbers, warnings. */
 function summarizeSlice(sol) {
     return sol.slices
         .map((s) => {
@@ -26,6 +28,7 @@ function summarizeSlice(sol) {
     })
         .join("\n");
 }
+/** Renders results as a colored terminal table, with an optional details footer. */
 export function renderTable(result) {
     if (result.solutions.length === 0) {
         return chalk.yellow("No flights found.");
@@ -44,5 +47,18 @@ export function renderTable(result) {
     }
     const header = chalk.dim(`${result.shown} of ${result.count} results` +
         (result.minPrice ? ` · from ${result.minPrice}` : ""));
-    return `${header}\n${table.toString()}`;
+    const footer = result.details ? `\n${renderDetails(result.details)}` : "";
+    return `${header}\n${table.toString()}${footer}`;
+}
+/** Top-result detail footer: fare construction (for travel agents) + Google Flights link. */
+function renderDetails(details) {
+    const lines = [chalk.bold("\nTop result")];
+    if (details.fareConstruction.length) {
+        lines.push(chalk.dim("Fare Construction (can be useful to travel agents):"));
+        lines.push(...details.fareConstruction.map((l) => `  ${l}`));
+    }
+    if (details.googleFlightsUrl) {
+        lines.push(`${chalk.bold("Open in Google Flights:")} ${details.googleFlightsUrl}`);
+    }
+    return lines.join("\n");
 }

package/docs/ROUTING_CODES.md

@@ -41,6 +41,8 @@ Define which carriers / airports / operators a slice may use, and in what order.
 | `C:XX` | force **marketing** carrier | `C:BA` |
 | `O:XX` | force **operating** carrier | `O:AA` |
 | `X:AAA` | **require** connection at airport | `X:DFW` |
+| `X` | any single connection point | `UA X UA` |
+| `X?` | nonstop **or** one connection | `X?` |
 | `N:` | nonstop only (no connections) | `N:` |
 | `F:` | direct (single flight number, stops allowed) | `F:` |
 
@@ -96,6 +98,9 @@ pipe-(`|`)-separated.
 | No red-eyes | `-REDEYES` | `-REDEYES` | exclude red-eye flights |
 | No overnights | `-OVERNIGHTS` | `-OVERNIGHTS` | exclude overnight layovers |
 | No props | `-PROPS` | `-PROPS` | exclude propeller aircraft |
+| No airport change | `-CHANGE` | `-CHANGE` | exclude connections that change airports in a city |
+| No trains | `-TRAIN` | `-TRAIN` | exclude rail segments |
+| No helicopters | `-HELICOPTER` | `-HELICOPTER` | exclude helicopter segments |
 
 ### Faring codes (`f` / booking class / fare basis)
 
@@ -123,7 +128,27 @@ pipe-(`|`)-separated.
 
 ---
 
-## 3. Notes for the skill
+## 3. Power-user strategies (FlyerTalk / community)
+
+Higher-leverage patterns that combine the primitives above:
+
+- **Force a stopover / overnight.** Matrix has no "stopover" command — fake it with a large
+  minimum connection. `MINCONNECT 12:00` forces an overnight layover; values above `24:00`
+  (e.g. `MINCONNECT 30:00`) force a 24 h+ stopover. Pin *where* with `X:CITY` in Routing.
+  Pair with `MAXCONNECT` to bound it: `X:NRT` + `MINCONNECT 20:00; MAXCONNECT 30:00`.
+- **Split marketing vs operating for mileage credit.** Force the metal you want with `O:` in
+  Routing and the program you want to credit with marketing carrier / `ALLIANCE`. E.g. fly
+  Lufthansa metal but ticket via a partner: Routing `O:LH+`, Extension `ALLIANCE star-alliance`.
+- **Target a booking class for upgrades / earning.** `f bc=...` pins the prime booking code
+  (fare buckets differ in price, upgrade eligibility, and miles earned). `f bc=w|bc=v` allows
+  either. Combine with `+CABIN` to keep the displayed cabin honest.
+- **Mileage-run / distance tuning.** `MINMILES`/`MAXMILES` shape itinerary distance; useful for
+  hitting an elite-qualifying threshold or avoiding wasteful backtracking.
+- **Consider nearby airports.** Matrix's UI accepts comma-separated origins/destinations
+  (e.g. `BOS,PVD,MHT`) and secondary airports are often materially cheaper; if a single-field
+  comma string is rejected, fall back to one search per airport and compare.
+
+## 4. Notes for the skill
 
 - **Validate field placement**: path-shaped intent → Routing; filter/fare intent → Extension.
 - **Cabin two ways**: the top-level `--cabin` (search option) sets the *displayed* cabin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itamatrix",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "CLI for ITA Matrix flight search",
   "type": "module",
   "bin": {

package/skills/itamatrix/SKILL.md

@@ -18,7 +18,9 @@ request into the right command + flags, encoding advanced intent as ITA
 
 The CLI ships as `itamatrix` (`npx itamatrix ...` if not installed globally).
 On first use it may ask for the browser: `npx playwright install chromium`.
-Queries take 30–60 s (Matrix is slow server-side); repeated queries hit the cache.
+Queries can take a while (Matrix is slow server-side); repeated queries hit the
+cache. **Set the command timeout to at least 180 s** — a search may run that long
+before returning. Don't kill it early and conclude it failed.
 
 Always run with `--json` so you get structured output to parse and summarize.
 
@@ -45,6 +47,25 @@ flag can't express it.
 | "only UA and AA" (simple) | `--carriers UA,AA` |
 | number of travelers | `--adults N` |
 | how many results | `--limit N` (1–25 for search/multicity) |
+| fare construction + Google Flights link | `--details` (search/multicity) |
+
+## Fare construction & Google Flights link (`--details`)
+
+`--details` (on `search` and `multicity`) opens the **top result's** itinerary
+detail page and adds two things to the output:
+
+- **Fare Construction** — the NUC fare-basis breakdown ITA labels "can be useful
+  to travel agents" (e.g. `BOS B6 LON 70.00OL8LBVL1 NUC 70.00 END ROE 1.00 XT
+  …`). Surface it verbatim; agents/ticketing desks read it directly.
+- **Open in Google Flights** — the detail page's deep link
+  (`google.com/travel/flights?tfs=…&source=ita_matrix`) for the same itinerary.
+
+It costs an extra page navigation and **bypasses the cache** (the link needs the
+live solution session), so only pass it when the user wants the fare detail or a
+hand-off link. Detail is best-effort: if the page can't be opened the search
+results still return, just without the `details` block. In JSON it's a top-level
+`details: { fareConstruction, googleFlightsUrl }`; in table output it's a footer
+under the results. **Show both to the user when present.**
 
 ## Encode advanced intent → routing / extension codes
 
@@ -62,6 +83,17 @@ grammar before constructing codes. Rules of thumb:
 - The `f` faring grammar is community-documented, not official — let Matrix
   validate. Don't over-restrict locally.
 
+### High-leverage patterns (see the reference doc's "Power-user strategies")
+
+- **Force a stopover/overnight** — Matrix has no stopover command; fake it with a
+  big minimum connection. "Overnight in Tokyo" → `--routing X:NRT --ext "MINCONNECT 12:00"`;
+  24 h+ stopover → `MINCONNECT 30:00`.
+- **Mileage credit / specific metal** — force operating carrier in `--routing` (`O:LH+`)
+  and the crediting program via `--ext "ALLIANCE star-alliance"`.
+- **Upgrade/earning fare buckets** — pin booking class with `--ext "f bc=w|bc=v"`.
+- **Time format gotcha**: `--ext` uses `h:mm` (`MINCONNECT 12:00`); the inline
+  `--routing / minconnect 720` form uses raw minutes. Prefer `--ext`.
+
 ## Workflow
 
 1. Parse the request: route(s), dates, travelers, and any constraints.
@@ -109,6 +141,7 @@ Search one-way or round-trip flights
 | `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
 | `--routing <codes>` | ITA routing codes (path) — see docs/ROUTING_CODES.md |
 | `--ext <codes>` | ITA extension codes (faring/filters) — see docs/ROUTING_CODES.md |
+| `--details` | also fetch the top result's fare construction + Google Flights link (live, skips cache) |
 | `--headful` | show the browser window (debug) |
 
 ### `multicity`
@@ -126,6 +159,7 @@ Search a multi-city itinerary (N legs)
 | `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
 | `--routing <codes>` | ITA routing codes applied to every leg |
 | `--ext <codes>` | ITA extension codes applied to every leg |
+| `--details` | also fetch the top result's fare construction + Google Flights link (live, skips cache) |
 | `--headful` | show the browser window (debug) |
 
 ### `calendar <origin> <dest>`
@@ -165,9 +199,23 @@ itamatrix --json multicity \
   --ext "-OVERNIGHTS"
 ```
 
+> "Boston to Singapore in October, but I want a long overnight stopover in Tokyo."
+
+```bash
+itamatrix --json search BOS SIN --depart 2026-10-10 \
+  --routing "X:NRT" --ext "MINCONNECT 12:00; MAXCONNECT 30:00"
+```
+
 > "What's the cheapest week in August to do a 7-night trip BOS→LAX on United?"
 
 ```bash
 itamatrix --json calendar BOS LAX \
   --depart-range 2026-08-01:2026-08-31 --trip-length 7 --carriers UA
 ```
+
+> "Cheapest BOS→LON next August, and give me the fare construction and a Google Flights link for the top one."
+
+```bash
+itamatrix --json search BOS LON --depart 2026-08-15 --details
+# → result.details.fareConstruction[] + result.details.googleFlightsUrl
+```