docs(wiki): the pages the 4.3.1 changes left behind

The check-in is an anchor now, not an earliest arrival, and a booked night leads its check-in day, which the road trip and accommodation pages said otherwise. Upgrading gains a 4.3.1 section for the reseat migration and for what better-sqlite3 13 asks of a source install. The collaboration page knows that links are chips and editable, the audit log knows the new admin action and the SSO register row, and the MCP pages know the provider parameter and the Google-only switch.
2026-10-18 21:16:47 +00:00 · 2026-09-22 12:10:21 +02:00
parent 85b5756e89
commit 2dd77aaac1
10 changed files with 50 additions and 20 deletions
@@ -45,13 +45,27 @@ The two views show the same night differently, and both are the whole picture:

 - **Days** keeps it in the day header, as the badge it has always been. The stop itself is
  hidden there, because the row would be that same hotel a second time.
- **Road Trip** draws it as a service stop in the driving chain, which is the view that
-  needs to know where the day ends.
+- **Road Trip** draws it as a service stop in the driving chain, anchored on its
+  check-in the way a pinned time anchors any other stop: the day is built to be there
+  by then, and a drive that cannot make it is reported late.

 A few details worth knowing:

 - Only the check-in day gets a stop, however many nights the stay runs. That is the day
  you travel there; the later nights keep showing as badges in the day header.
+- The stop leads its check-in day. It is seated first, behind only a stop whose own time
+  is at or before the check-in, and the stops that carry no hour follow it. A night
+  without a check-in is seated first too, a new check-in seats the stop afresh, and two
+  nights booked on one day settle by their check-ins. When those match, or neither night
+  has one, the booking made first leads.
+- That also means a night booked for the end of a driving day heads that day when its
+  stops carry no time of their own. To put the hotel back at the end, drag it down the
+  day in the Road Trip rail, where an edit to the booking that leaves the check-in alone
+  will not move it back. A start time at or before the check-in does it as well, as long
+  as it goes on the first stop after the hotel: the day re-sorts by time and the untimed
+  stops behind that one follow it. On the last stop alone it is not enough, because the
+  untimed stops in front of it keep counting as being at the check-in and stay behind
+  the hotel.
 - The place is marked as a **hotel** stop, which is why it carries no number in the Road
  Trip rail and does not count towards the day's stop total. If you had already given the
  place a stop type of your own, that one is kept.
@@ -63,15 +77,17 @@ A few details worth knowing:
  Trip settings also decides whether they appear in the places list.

 Nights booked before this existed are given their stop when the server upgrades, so trips
-you already have show their hotels on the drive without anyone re-saving anything.
+you already have show their hotels on the drive without anyone re-saving anything. Trips
+planned before 4.3.1 are seated the same way on upgrade, see
+[Upgrading to 4.3.1](Updating#upgrading-to-431).

 ## In the day plan sidebar

 Accommodations appear as small colour-coded badges in the day header row of the day plan sidebar:

- **Green badge** — check-in day
- **Red badge** — check-out day
- **Neutral badge** — nights in between (ongoing stay)
+- **Green badge**: check-in day
+- **Red badge**: check-out day
+- **Neutral badge**: nights in between (ongoing stay)

 Clicking a badge navigates to the linked place. Hotel-type reservations are filtered out of the inline transport card list between places; they do not appear as transport items in the timeline.

@@ -25,7 +25,7 @@ Actions are grouped by area below. The **Action key** is the raw value stored in
 | `user.password_reset_success` | Password reset completed |
 | `user.password_reset_fail` | Password reset attempt rejected (`reason` in details) |

-A request for an account that can actually be reset writes **two** rows: one with `delivered: "pending"` when the mail is handed off, one with the delivery result. Every other outcome writes a single row carrying a `reason` instead — `no_user`, `oidc_only`, `throttled_per_email` or `password_login_disabled`. Passkey logins are not a separate key: they land as `user.login` with `method: passkey` in the details, and SSO logins the same way with `method: oidc`.
+A request for an account that can actually be reset writes **two** rows: one with `delivered: "pending"` when the mail is handed off, one with the delivery result. Every other outcome writes a single row carrying a `reason` instead — `no_user`, `oidc_only`, `throttled_per_email` or `password_login_disabled`. Passkey logins are not a separate key: they land as `user.login` with `method: passkey` in the details, and SSO logins the same way with `method: oidc`. An account created by a first SSO login also writes `user.register` with `method: oidc`, carrying the same fields as a password signup.

 ### MFA

@@ -78,6 +78,7 @@ A request for an account that can actually be reset writes **two** rows: one wit
 | `admin.places_details` | Places details feature toggled |
 | `admin.places_enrich` | Place enrichment feature toggled |
 | `admin.place_shadow` | Place Search Log toggled (`enabled` in details) |
+| `admin.places_google_only` | Search with Google only toggled (`enabled` in details) |
 | `admin.collab_features` | Collaboration features updated |
 | `admin.transit_provider` | Public transit backend changed (`provider` in details: `transitous` or `google`) |
 | `admin.packing_template_create` | Packing template created |
@@ -236,8 +236,8 @@ These tools work without an open browser. The external assistant chooses places

 | Tool | Purpose | Scope |
 |---|---|---|
-| `get_roadtrip_context` | Saved days, visits, coordinates, stays, pinned times, vehicle preferences, route profiles, vias, tracks and manual boundaries | `trips:read` |
-| `calculate_roadtrip` | Calculated days, arrivals, departures, automatic pauses, driving warnings and range warnings; optional geometry | `trips:read` |
+| `get_roadtrip_context` | Saved days, visits, coordinates, stays, pinned times, vehicle preferences, route profiles, vias, tracks and manual boundaries, plus a `carriers` block with the flight, train, ferry, cruise and bus bookings that seam the drive and the hire cars whose desks stand on it | `trips:read` |
+| `calculate_roadtrip` | Calculated days, arrivals, departures, automatic pauses, driving warnings and range warnings; optional geometry. A booking's terminals and a hire car's desks come back as stops carrying `carrier` (its role, type and timetable); their `assignmentId` and `placeId` are synthetic negative numbers that belong to no assignment and no place, so never pass them to the assignment or place tools | `trips:read` |
 | `get_roadtrip_settings` | Shared driving preferences for the specified trip | `trips:read` |
 | `update_roadtrip_settings` | Patch shared trip driving preferences, preserving other settings | `trips:write` |
 | `search_roadtrip_corridor` | Fuel, charging, rest areas, campsites, food, sights or hotels along a day | `trips:read` |
@@ -68,7 +68,7 @@ Requires `places:read` or `places:write` scope.
 | `create_category` | Add a category to the instance-wide palette, with name, hex colour and emoji icon. Every trip on the instance sees it, so prefer an existing one from `list_categories`. Admin only; a non-admin gets `Admin access required`. Requires `places:write`. |
 | `update_category` | Rename a category or change its colour or icon. Every place already carrying it follows the change. Admin only. Requires `places:write`. |
 | `delete_category` | Remove a category from the palette. Places keep their data but lose the category, across every trip. Admin only. Requires `places:write`. |
-| `search_place` | Search for a place by name or address, the way the full search in the app does: TREK's own place index and OpenStreetMap together, and Google or Amap only when both are empty. Returns `osm_id` (and `google_place_id` / `google_ftid` when Google answered) for use in `create_place`. Takes an optional `locationBias` to rank results around the trip's destination. |
+| `search_place` | Search for a place by name or address, the way the full search in the app does: TREK's own place index and OpenStreetMap together, and Google or Amap only when both are empty. Returns `osm_id` (and `google_place_id` / `google_ftid` when Google answered) for use in `create_place`. Takes an optional `locationBias` to rank results around the trip's destination, and an optional `provider: 'google'` that sends this one search to Google Places alone, the same as the **Search Google instead** line under a result list in the app; it is ignored unless Google holds the keyed slot: an instance without a Google key, or one whose admin picked Amap or OpenStreetMap as the places provider, answers from the index and OpenStreetMap as usual. With the admin switch **Search with Google only** on (see [Places-and-Search](Places-and-Search#with-a-google-maps-api-key)), every call goes to Google whatever is passed, and the index and OpenStreetMap are never asked, so no result carries an `osm_id`. |
 | `search_places_via_plugins` | Search the place indexes installed plugins provide, alongside `search_place` rather than instead of it. Results have the shape `search_place` returns plus a `rating` and the `pluginId` that found them; only these results can carry a rating. Empty when no plugin offers a search index. Requires `places:read`. |

 ### Day Planning
@@ -57,8 +57,8 @@ A key does not buy a different search by itself. Google fills the slot that answ

 That order means a search the index answered with the wrong place never reaches Google on its own. Two ways to send it there:

- **Per search:** under a result list that did not come from Google, a small line reads **Not the right place? Search Google instead**. It sends the same query to Google Places alone, once, and the results carry the Google mark. The line only appears on an instance with a Google key, on the desktop form and the phone's search sheet alike.
- **For every search:** the switch **Search with Google only** in the key's block (below) sends every search and every suggestion to Google Places and asks nothing of the TREK API or OpenStreetMap. Off, the order above applies. The switch does nothing without a key, and nothing while Amap or OpenStreetMap is picked as the provider.
+- **Per search:** under a result list that did not come from Google, a small line reads **Not the right place? Search Google instead**. It sends the same query to Google Places alone, once, and the results carry the Google mark. The line only appears where a search can reach Google at all: an instance with a Google key, and with neither Amap nor OpenStreetMap picked as the provider, the same rule the switch below follows. Desktop form and phone search sheet alike. The MCP tool `search_place` does the same with `provider: 'google'`, see [MCP-Tools-and-Resources](MCP-Tools-and-Resources).
+- **For every search:** the switch **Search with Google only** in the key's block (below) sends every search and every suggestion to Google Places and asks nothing of the TREK API or OpenStreetMap, from the app and from `search_place` alike. Off, the order above applies. The switch does nothing without a key, and nothing while Amap or OpenStreetMap is picked as the provider. Switching it on or off is recorded in the [Audit Log](Audit-Log) as `admin.places_google_only`.

 The key's block carries five switches under **What the key may be used for**:

@@ -68,7 +68,7 @@ The key's block carries five switches under **What the key may be used for**:
 | **Place Autocomplete** | The suggestions while you type. |
 | **Place Details** | The details of a place: hours, rating, website. |
 | **Place Enrichment** | The **Place details** column in the place form, see [below](#place-details-while-searching). |
-| **Search with Google only** | Every search and every suggestion goes to Google Places instead of the TREK API and OpenStreetMap. Off by default; the per-search line above stays available either way. |
+| **Search with Google only** | Every search and every suggestion goes to Google Places instead of the TREK API and OpenStreetMap. Off by default. On, every list already comes from Google, so the per-search line above has nothing to offer and does not appear; off, the line appears under lists the TREK API or OpenStreetMap produced. |

 > **Place Autocomplete and Place Details act on every provider**, not only on Google. Switched off, the suggestion dropdown stays empty and details lookups stop for the TREK API and OpenStreetMap too; the full search keeps working. Leave both on unless that is what you want.

@@ -44,7 +44,7 @@ On **desktop** the panel shows Chat as a fixed 380 px column on the left when ot

 ### Links

-The **Links** tab collects the web addresses a trip runs on: the booking portal, the shared photo album, the restaurant's menu. **Add link** asks for a title and an `http(s)` address; anything else is refused. Each link opens in a new tab, and members with `collab_edit` can **pin** it to the top of the list or **delete** it. Pinned links come first, then the newest. Adding, pinning and deleting show up for every connected member at once.
+The **Links** tab collects the web addresses a trip runs on: the booking portal, the shared photo album, the restaurant's menu. **Add link** asks for a title and an `http(s)` address; anything else is refused. Each link is a chip with the site's favicon, the title and the host, two to a row where the panel is wide enough and one to a row where it is narrow, as in the Collab tab on the phone; a pinned chip is drawn in the accent tint. The whole chip is the link and opens the address in a new tab. Members with `collab_edit` can **edit** it in place (the pencil, for title and address alike), **pin** it to the top of the list or **delete** it, which asks first because the link goes for every member; the three sit faint in the chip's tail and come forward on hover, and are always shown on touch. Pinned links come first, then the newest. Adding, editing, pinning and deleting show up for every connected member at once.

 ## Conflict handling

@@ -112,7 +112,7 @@ Give a visit a **Start** in the place form and the chain restarts from it. That
 - With nothing to count from (no pinned time, no check-in and no daily travel times), the rail shows driving times but no clock times.
 - **The schedule works backwards too.** Pin 10:00 on the second stop and the first one says when to set off, worked out from the drive and the stay. It stops at a leg that has not routed rather than inventing a duration.
 - A stop reached later than the time you set says so: *Arrives 15 min after the time you set*. The same warning appears on a fuel or charging halt that carries a time.
- The **Check-in** of a booked night is not an appointment. Arriving before it means waiting for it, and it starts the day when nothing before it decides the hour. Arriving after it is simply arriving.
+- The **Check-in** of a booked night holds its stop the way a pinned time does: the day is built to be there by then, the chain restarts from it, and a drive that gets there later is late, with the same *Arrives 15 min after the time you set* warning a missed pin gets. A time pinned on the stop itself wins over the check-in.

 ## Daily travel times and day endings

@@ -277,9 +277,13 @@ A night booked anywhere, whether in the day panel, the booking form, on the phon

 - **Days** shows the night in the day header as always, and hides the stop so the hotel is not listed twice.
 - Moving the booking to another day moves its stop along; deleting the booking removes the stop it created. A stop you placed yourself is left standing.
- The drive uses the booking's **Check-in** as the earliest arrival and the place's stay as its length. The check-out stays a booking detail.
+- The drive uses the booking's **Check-in** to anchor the stop, the way a pinned time anchors any other, and the place's stay as its length. A drive that cannot make the check-in is reported late. The check-out stays a booking detail.
+- **The night leads its day.** Its stop is seated first, behind only a stop whose own time is at or before the check-in, and the stops that carry no hour follow it: a hotel booked for ten in the morning is reached at ten, not at a quarter past twelve behind a whole day of untimed stops. A night without a check-in is seated first as well, a new check-in seats the stop afresh, and two nights booked on one day settle by their check-ins. A day that is nothing but its booked night stands among the days with the hotel and its check-in, instead of under the *Only {name} so far* placeholder.
+- One consequence to be aware of: a night booked for the end of a driving day heads that day too when its stops carry no time of their own, so the drive reads hotel first. To put the hotel back at the end, drag it down the rail: an edit to the booking that leaves the check-in alone will not undo that. A **Start** at or before the check-in does it as well, as long as it goes on the *first* stop after the hotel: the day re-sorts by time, and the untimed stops behind that one follow it. On the last stop alone it is not enough, because the untimed stops in front of it keep counting as being at the check-in and stay behind the hotel.
 - **Add as an overnight stay** from the search books the night and adds the stop in one go. The night runs to the next day; change the dates under **Days**. On the phone, booking a night works in the desktop planner only.

+Trips planned before 4.3.1 were seated the same way when the server upgraded, see [Upgrading to 4.3.1](Updating#upgrading-to-431).
+
 See [Accommodations](Accommodations#on-the-route) for the details.

 ## Flights, trains and ferries on the drive
@@ -337,8 +341,8 @@ With the [MCP](MCP-Overview) addon on as well, an assistant can plan and check a

 | Tool | What it does | Scope |
 |---|---|---|
-| `get_roadtrip_context` | Reads the saved days, visits, pinned times, End times, stays, kinds of stop, vias, followed tracks and day endings. | `trips:read` |
-| `calculate_roadtrip` | Works out arrivals, departures, day splits, driving limit and range warnings. Missing coordinates and routing failures are reported, not hidden. | `trips:read` |
+| `get_roadtrip_context` | Reads the saved days, visits, pinned times, End times, stays, kinds of stop, vias, followed tracks and day endings, plus a `carriers` block with the flight, train, ferry, cruise and bus bookings that seam the drive and the hire cars whose desks stand on it. | `trips:read` |
+| `calculate_roadtrip` | Works out arrivals, departures, day splits, driving limit and range warnings. Missing coordinates and routing failures are reported, not hidden. A booking's terminals and a hire car's desks come back as stops carrying `carrier` (its role, type and timetable); their `assignmentId` and `placeId` are synthetic negative numbers that belong to no assignment and no place, so never pass them to the assignment or place tools. | `trips:read` |
 | `get_roadtrip_settings`, `update_roadtrip_settings` | Read or change the trip's shared driving settings. | `trips:read`, `trips:write` |
 | `search_roadtrip_corridor` | Searches along a calculated day, with the same kinds, filters and sources as the panel. It never adds anything. | `trips:read` |
 | `list_route_vias`, `add_route_via`, `add_route_vias`, `update_route_via`, `reanchor_route_vias`, `remove_route_via` | List, add, move, re-pin and remove via points. | `trips:read`, `trips:write` |
@@ -39,6 +39,8 @@ Names are the ones the index has, which are the names used on the spot. The inde
 | Preparing a trip for offline use | Up to 3000 places around the trip, in one request | Nothing is cached, and offline search has nothing to answer from |
 | MCP: `search_place` and `search_pois` | The same as the full search and the category buttons | The same fallbacks |

+Where Google holds the keyed slot (a Google key, with neither Amap nor OpenStreetMap picked as the places provider), two things skip the index and OpenStreetMap for a search: the **Search Google instead** line under a result list (`provider: 'google'` on `search_place`) sends that one search to Google Places alone, and the admin switch **Search with Google only** sends every search and every suggestion there, `search_place` included; the category buttons and `search_pois` keep asking the index. See [Google and Amap](Places-and-Search#google-and-amap).
+
 Right-click reverse geocoding on the map does not use it: that is OpenStreetMap's (or Amap's inside mainland China, when Amap holds the keyed slot).

 ### Why two sources
@@ -27,7 +27,7 @@ Each sidebar has a drag handle on its inner edge for resizing.

 A **Day Detail panel** floats over the map area when you open a specific day, showing the weather forecast, that day's reservations, and the accommodation block. It can be collapsed to a slim header bar without closing it.

-Opening a day also narrows the Places sidebar. With a day selected, the **Planned** filter lists and counts only the places on that day's plan, the same set the map draws, and a line under the filter tabs says **Showing the open day only**. Its **X** closes the day again, so list, count and map return to the whole trip. **All** and **Unplanned** stay trip-wide on purpose: a place on some other day is planned, whichever day happens to be open.
+Opening a day also narrows the Places sidebar. With a day selected, the **Planned** filter lists and counts only the places on that day's plan, the same set the map draws, and a line under the places filter (the select that offers **All**, **Unplanned** and **Planned**, plus **Tracks** once the trip has one, each with its count in the menu) says **Showing the open day only**. Its **X** closes the day again, so list, count and map return to the whole trip. **All** and **Unplanned** stay trip-wide on purpose: a place on some other day is planned, whichever day happens to be open.

 ## Tabs

@@ -136,7 +136,7 @@ The Add as a stop dialog offers trivago and CHECK24 for hotels, or PiNCAMP and P

 All Looking for categories, including accommodation, are added as Roadtrip service stops. In Roadtrip mode, Edit in a planned place's details opens the stop dialog with its saved duration and check-in time. Saving updates the existing stop; More details still opens the full place editor. The shared stop-type contract also accepts hotel through MCP.

-A booked night uses its check-in as the earliest arrival and the place's STAY as its length. The drive never reads the check-out: it is the latest the room has to be handed back, not the time anybody drives on, so it stays a booking detail under Days. To leave at a set hour, give the visit an End, see [Road-Trip](Road-Trip#leaving-at-a-set-time). Explicit arrival times remain authoritative. Browser planning and MCP use the same scheduling logic.
+A booked night is anchored on its check-in the way a pinned time anchors any other stop, and takes the place's STAY as its length: the day is built to be there by then, and a drive that gets there later is reported late rather than moving the stop. A time pinned on the stop itself wins over the check-in. The drive never reads the check-out: it is the latest the room has to be handed back, not the time anybody drives on, so it stays a booking detail under Days. To leave at a set hour, give the visit an End, see [Road-Trip](Road-Trip#leaving-at-a-set-time). Browser planning and MCP use the same scheduling logic.

 The overnight dialog prefills check-in from the calculated arrival when available; existing manual check-in values take priority. Before adding a corridor result, the suggested arrival is estimated along the current routed leg.

@@ -97,6 +97,13 @@ A few defaults change with 4.3.0. None of them needs a manual step, but they are
 - **Booked nights get a stop.** A migration puts every existing stay that has a place on its check-in day as a hotel stop, so the trips you already have show their hotels in the [Road-Trip](Road-Trip) view without anyone re-saving a booking. Under **Days** nothing changes: that stop stays hidden behind the badge the booking already shows. See [Accommodations](Accommodations).
 - **Two things are on by default.** The **Links** tab in Collab, which an admin switches off under **Admin → Addons**, and the routing counters, daily totals of the route requests the planner makes that never leave the instance. An admin reads them at `/api/route-usage/summary`; an `app_settings` row named `route_usage_enabled` with the value `false` switches them off.

+## Upgrading to 4.3.1
+
+Two things change with 4.3.1. Neither needs a manual step on Docker, but they are worth knowing before you pull the image:
+
+- **Booked nights lead their day.** A migration moves every booked night to the head of its check-in day, behind only a stop whose own time is at or before the check-in, and the stops without an hour follow it: a hotel booked for ten in the morning is reached at ten in the [Road-Trip](Road-Trip) view, not at a quarter past twelve behind a whole day of untimed stops. A night booked for the end of a driving day heads that day too when its stops carry no time of their own, so such a day now reads hotel first. A via point drawn on the road into that hotel from the stop that is now last is removed, because that leg no longer exists in the day, the same way a drag would remove it; the other vias follow their stops. Under **Days** nothing changes. To put a hotel back at the end, drag it down the day in the Road Trip rail, or give the first stop after it a start time at or before the check-in, which brings the untimed stops behind that one along; a time on the last stop alone leaves the hotel in the middle of the day. See [Accommodations](Accommodations#on-the-route).
+- **Source installs need a build toolchain, or `--ignore-scripts`.** The server runs better-sqlite3 13, which ships its binaries inside the package, so nothing is compiled any more; the Docker image and the Helm chart are unaffected. On an install that runs `npm ci` itself, outside Docker, a lockfile-driven `npm ci` still runs node-gyp against those binaries and stops without Python 3 and a C++ toolchain (`build-essential` on Debian/Ubuntu, the Xcode Command Line Tools on macOS, the Visual Studio Build Tools on Windows; npm/cli#9837). Either keep those installed, as [Development-environment](Development-environment) lists them, or run `npm ci --ignore-scripts`, which is what the image does.
+
 ## Encryption Key Note

 If you are upgrading from a version that predates the dedicated `ENCRYPTION_KEY` (i.e. you have no `ENCRYPTION_KEY` environment variable set), TREK automatically falls back to `./data/.jwt_secret` on startup and immediately promotes it to `./data/.encryption_key`. No manual steps are required — the transition is handled at first boot after the upgrade.