@aitne-sh/aitne 0.1.8 → 0.1.10

package/agent-assets/docs/features/integrations/obsidian.md

@@ -16,6 +16,7 @@ tags:
   - integrations
   - knowledge
   - observations
+  - obsidian
 status: stable
 ask_examples:
   - How do I connect my Obsidian vault?
@@ -23,7 +24,7 @@ ask_examples:
   - Why didn't the agent see my new note?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - obsidian
   - vault
@@ -36,15 +37,20 @@ related:
 ui_anchors:
   - /connections/knowledge
 config_keys:
+  - externalObsidianVaultPath
+  - externalObsidianVaultName
+  - externalObsidianWatch
   - obsidianDebounceSeconds
 ---
 
 # Obsidian
 
-## In One Sentence
+Point Aitne at your Obsidian vault directory; new and changed notes
+record observations the hourly check consumes. The agent can read and
+write vault notes through the `external-services` skill.
 
-Point Aitne at your Obsidian vault directory; new and changed
-notes record observations the hourly check consumes.
+Reads and writes go through the Obsidian app's CLI — the Obsidian app
+must be running, or vault read/write calls fail.
 
 ## What It Does
 
@@ -52,9 +58,22 @@ notes record observations the hourly check consumes.
 - Filters out agent-originated writes via `AgentWriteTracker`.
 - Records observations for genuine operator edits.
 
+### Will it edit my notes?
+
+The agent reads on demand and can create, append to, overwrite, or
+delete notes when you ask it to (via the `external-services` skill). It
+never edits your vault unprompted. When the agent does write, the
+watcher does not treat its own writes as new observations —
+`AgentWriteTracker` suppresses them — so the agent does not re-observe
+its own output.
+
 ## When It Runs / How It Is Triggered
 
-Continuously. The watcher is debounced by `obsidianDebounceSeconds`.
+Continuously — the watcher runs as long as the daemon is up and a vault
+path is configured (`externalObsidianWatch=true`). Saves are debounced
+by `obsidianDebounceSeconds` before an observation is recorded; the
+[hourly check](../routines/hourly-check.md) later consumes those
+observations.
 
 ## Where in the Dashboard
 
@@ -64,10 +83,14 @@ Continuously. The watcher is debounced by `obsidianDebounceSeconds`.
 
 | Setting | Default | Notes |
 |---|---|---|
+| `externalObsidianVaultPath` | unset | Vault directory; set in Connections → Knowledge. |
+| `externalObsidianWatch` | true | Set false to keep the path but stop recording changes (large-vault churn control). |
 | `obsidianDebounceSeconds` | 5 | How long to wait after a save before recording. |
 
 ## When Something Goes Wrong
 
+- A vault read or write that failed: the Obsidian app must be running,
+  since reads and writes proxy through its CLI. Open Obsidian and retry.
 - A change that did not record: the debounce may have folded multiple
   saves; the next one will fire.
 

package/agent-assets/docs/features/lifestyle/git.md

@@ -26,9 +26,9 @@ tags:
   - lifestyle
   - git
   - github
-  - automation
+  - autonomous
   - observations
-  - architecture
+  - core
 status: stable
 ask_examples:
   - What is the My Life › Git page for?
@@ -46,7 +46,7 @@ ask_examples:
   - How much does one Architecture refresh cost?
 locale: en-US
 created: 2026-05-05
-updated: 2026-05-17
+updated: 2026-06-07
 keywords:
   - my life
   - git
@@ -69,6 +69,20 @@ ui_anchors:
   - /connections/repositories
 config_keys:
   - gitPollIntervalSeconds
+process_keys:
+  - git.project.init
+  - git.project.update
+  - git.project.refresh_architecture
+  - git.project.retemplate
+api_endpoints:
+  - PUT /api/repositories/:id/architecture-section
+  - POST /api/repositories/:id/management/init
+  - POST /api/repositories/:id/management/refresh-architecture
+  - POST /api/repositories/:id/management/scan
+context_files:
+  - knowledge/repos/<slug>/overview.md
+  - knowledge/repos/<slug>/README.md
+  - journal/repos/<slug>/<date>.md
 ---
 
 # My Life — Git
@@ -86,8 +100,7 @@ mirror of the source README.
 
 The page lists every repository registered on
 **Connections → Repositories** and exposes three collapsible sections
-per repo (now **all open by default** so the controls are visible at
-a glance):
+per repo (all open by default so the controls are visible at a glance):
 
 1. **Polling** — overrides the global `gitPollIntervalSeconds` for
    this repository alone. Useful when one repo is high-traffic and
@@ -97,17 +110,17 @@ a glance):
 2. **Triggers** — fire when matching Git or GitHub events arrive on
    this repository. Triggers run **alongside** the project-wide
    task-flow defaults, not in place of them. Each trigger has a
-   workdir mode (`local-clone` or `ephemeral`); local-clone triggers
+   workdir mode (`local-clone` or `temp`); local-clone triggers
    require the repository to have a `localPath`.
 3. **Daily git management** — opt-in per repo. Enabling it does three
    distinct kinds of work, on different cadences:
    - On the first **Run init now** click, writes the curated
-     `git/<slug>/overview.md` skeleton, mirrors the source `README.*`
-     to `git/<slug>/README.md`, and **automatically queues a
-     one-shot Architecture refresh** so the AI agent fills in the
-     deep Architecture section for you.
-   - Once a day, the `repository-management-cron` observer iterates
-     enabled rows and writes `git/<slug>/journal/YYYY-MM-DD.md` if
+     `knowledge/repos/<slug>/overview.md` skeleton, mirrors the source
+     `README.*` to `knowledge/repos/<slug>/README.md`, and
+     **automatically queues a one-shot Architecture refresh** so the AI
+     agent fills in the deep Architecture section for you.
+   - Once a day, the `RepositoryManagementCron` observer iterates
+     enabled rows and writes `journal/repos/<slug>/YYYY-MM-DD.md` if
      there was activity, plus a one-line entry under
      `## Daily Activity Log` in `overview.md`.
    - **Refresh architecture** (the button) re-runs the Architecture
@@ -120,8 +133,9 @@ The agent never pushes, amends, or force-resets. Read-only by design.
 
 ## Architecture Section — Deep AI Analysis
 
-The `## Architecture` block of `git/<slug>/overview.md` is wrapped in
-`<!-- architecture:start -->` / `<!-- architecture:end -->` markers
+The `## Architecture` block of `knowledge/repos/<slug>/overview.md` is
+wrapped in `<!-- architecture:start -->` / `<!-- architecture:end -->`
+markers
 and contains a **module map, runtime shape, data flow, persistence
 model, integrations, build pipeline, and design choices** produced by
 a Sonnet-class agent that reads the actual code.
@@ -162,8 +176,8 @@ for recovery.
 
 ## README Mirror
 
-`git/<slug>/README.md` is a **mechanical verbatim copy** of the
-repository's `README.*` (whichever extension exists, with `.md`
+`knowledge/repos/<slug>/README.md` is a **mechanical verbatim copy** of
+the repository's `README.*` (whichever extension exists, with `.md`
 preferred). It is refreshed on:
 
 - Every **Run init now** (initial mirror).
@@ -201,13 +215,13 @@ README is rewritten.
 
 ## What It Outputs
 
-Per repository, under `<contextDir>/git/<slug>/`:
+Per repository, under `<contextDir>/`:
 
 | File | Source | Refresh cadence |
 |---|---|---|
-| `overview.md` | Daemon (skeleton + Notable Changes + journal log) + Agent (Architecture section) | Skeleton on init; Architecture on init/refresh; daily entry appended on each scan |
-| `README.md` | Verbatim copy of `<repo>/README.*` | Every init + every architecture refresh |
-| `journal/YYYY-MM-DD.md` | Daemon (commits + PR/workflow observations + diff stat) | Once per day per repo, when activity exists |
+| `knowledge/repos/<slug>/overview.md` | Daemon (skeleton + Notable Changes + journal log) + Agent (Architecture section) | Skeleton on init; Architecture on init/refresh; daily entry appended on each scan |
+| `knowledge/repos/<slug>/README.md` | Verbatim copy of `<repo>/README.*` | Every init + every architecture refresh |
+| `journal/repos/<slug>/<date>.md` | Daemon (commits + PR/workflow observations + diff stat) | Once per day per repo, when activity exists |
 
 Polling additionally produces `observation` rows in the database;
 triggers spawn autonomous sessions whose task-flow is selected by the
@@ -216,7 +230,10 @@ trigger's process key.
 ## Where in the Dashboard
 
 - **My Life → Git** (`/git`) — this page. Polling, Triggers, and Daily
-  git management are now all expanded by default.
+  git management are all expanded by default. The Daily-git-management
+  panel's buttons appear in lifecycle order — **Run init now → Refresh
+  architecture → Run today's scan now** — and each surfaces an inline
+  green confirmation on success or a red error message on failure.
 - **Connections → Repositories** (`/connections/repositories`) —
   register a repo (link a `localPath` and/or `owner/repo`), rename,
   set `local-only`, delete. The model-binding cards visible on this
@@ -226,24 +243,11 @@ trigger's process key.
   `github.pull_request.review_requested`, `github.workflow_run.failed`)
   were folded back into the default routing. To pin a different model
   for any of those, use **Settings → Models** instead.
-- **Knowledge** (`/knowledge?path=git/<slug>/overview`) — quick links
-  on each Daily-git-management panel open the generated overview, the
-  current day's journal, and (after the architecture refresh
-  completes) the AI-rich Architecture section in context.
-
-## UI polish (2026-05-07)
-
-- The Daily git management toggle is now a styled switch instead of a
-  raw checkbox — same behavior, more legible state.
-- Init / Refresh architecture / Run today's scan now buttons surface
-  inline confirmation messages (green) on success and inline error
-  messages (red) on failure, instead of the previous silent return.
-- The button order on the panel is **Run init now → Refresh
-  architecture → Run today's scan now**, matching the lifecycle order
-  (one-time skeleton → one-time deep analysis → daily increments).
-- The Polling, Triggers, and Daily git management collapsibles all
-  open by default so a freshly-loaded `/git` page exposes every
-  per-repo control without an extra click.
+- **Knowledge → Context Files** (`/knowledge?tab=context-files`) — quick
+  links on each Daily-git-management panel open the generated overview
+  (`knowledge/repos/<slug>/overview.md`), the current day's journal
+  (`journal/repos/<slug>/<date>.md`), and (after the architecture
+  refresh completes) the AI-rich Architecture section in context.
 
 ## Configuration
 
@@ -268,7 +272,7 @@ repository has a `localPath`:
 - **Triggers** with `workdirMode: "local-clone"` require a `localPath`
   on the parent repository (enforced when the trigger is created and
   again if you try to clear `localPath` while such a trigger exists).
-  Triggers with `workdirMode: "ephemeral"` work without a local clone.
+  Triggers with `workdirMode: "temp"` work without a local clone.
 - **Daily git management** is **local-clone-bound for v1**. The
   toggle is disabled and the dashboard surfaces "No local clone — link
   one to enable this feature." Internally the

package/agent-assets/docs/features/lifestyle/reading.md

@@ -11,8 +11,8 @@ category: features
 summary: |
   Track books and Kindle highlights in a SQLite-backed reading list
   surfaced at /reading. The schema covers title/author/status plus a
-  separate reading_highlights table populated from Kindle clipping
-  imports.
+  separate reading_highlights table populated from Kindle imports
+  (My Clippings.txt or an Export Notebook email).
 section: lifestyle
 tags:
   - lifestyle
@@ -21,20 +21,27 @@ tags:
 status: stable
 ask_examples:
   - How do I add a book to my reading list?
+  - How do I import my Kindle highlights?
   - Can the agent recommend something from my reading list?
   - Where do reading-list items get stored?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
   - reading
   - books
-  - articles
+  - highlights
+  - kindle
   - read later
 related:
   - features/memory-files/user-profile
   - features/lifestyle/receipts
   - features/lifestyle/travel-bookings
+api_endpoints:
+  - GET /api/books
+  - PATCH /api/books/:id
+  - POST /api/books/import-clippings
+  - POST /api/books/import-notebook-html
 ui_anchors:
   - /reading
 ---
@@ -44,22 +51,35 @@ ui_anchors:
 ## In One Sentence
 
 A reading list backed by the `books` and `reading_highlights` SQLite
-tables: imports Kindle clippings, tracks status (`reading`/`finished`/etc.),
-and surfaces the working set at `/reading`.
+tables: imports your Kindle highlights, tracks each book's status
+(`reading`, `completed`, or `abandoned`), and surfaces the working set
+at `/reading`.
 
 ## What It Does
 
-- **Add** items by DM ("agent, add 'The Soul of a New Machine' to my
-  reading list") — the agent inserts into `books` via the daemon
-  `/api/books` route.
-- **Import Kindle highlights** via `POST /api/books/import-clippings`,
-  which parses a `My Clippings.txt` paste and populates the
-  `reading_highlights` table linked back to `books.id`.
-- **List** what's outstanding on `/reading`.
-- **Mark complete** — the agent updates the row's `status` and
-  `completed_at` columns.
-- **Recommend** from the list during reactive turns when context
-  invites it.
+- **Import Kindle highlights** — the primary way books enter the list.
+  Two pipelines, both of which create any missing `books` rows and link
+  every highlight back to `books.id` in the `reading_highlights` table:
+  - `POST /api/books/import-clippings` parses a pasted `My Clippings.txt`.
+  - `POST /api/books/import-notebook-html` parses the HTML of a Kindle
+    "Export Notebook" email.
+- **List** the library on `/reading` or via `GET /api/books`
+  (filterable by `status` and `source`, paginated to 200 rows per call).
+- **Mark complete or abandoned** — an existing row is updated via
+  `PATCH /api/books/:id`. This is an **Approve-tier** write that requires
+  an operator `Authorization: Bearer` token, so it is driven from the
+  dashboard, not autonomously by the agent (an unauthenticated agent curl
+  is rejected with **401** before the handler runs). Setting `status` to
+  `completed` stamps `completed_at` automatically; you can also set a 1–5
+  `rating` or `notes`.
+- **Recommend** from the list during reactive turns, and refresh the
+  reading-taste profile during weekly and monthly reviews.
+
+There is **no bare "add a book" endpoint** — new books arrive through the
+two Kindle import pipelines above (or are created internally during an
+import); `PATCH` only edits books that already exist. If you ask the
+agent to "add a book" conversationally, it works from whatever import
+data it has rather than minting a free-form row.
 
 There is no Markdown context file for the reading list; the durable
 record is the SQLite row. If you want a parallel copy in your external
@@ -68,8 +88,13 @@ stays canonical in the database.
 
 ## When It Runs / How It Is Triggered
 
-Reactive only. There is no autonomous reading-list routine in the
-default install — the operator drives the list shape.
+There is no dedicated autonomous reading-list routine — the operator
+drives the list shape. The reading skill loads in two situations:
+
+- **Reactively**, when you mention a book or highlight in a DM.
+- **From existing routines** — the morning routine can mention what
+  you're currently reading, and the weekly and monthly reviews pull
+  reading progress and refresh the reading-taste profile.
 
 ## What It Outputs
 
@@ -83,9 +108,19 @@ default install — the operator drives the list shape.
 
 ## When Something Goes Wrong
 
-- A **missing add**: check the Activity row's tool calls — the agent
-  hits `/api/books`, so a network or quota error there will surface in
-  the audit log even when the chat reply looked fine.
+- **An import that produced no books**: check the Activity row's tool
+  calls — the agent hits `/api/books/import-clippings` (or
+  `/import-notebook-html`), so a parse failure, oversized payload, or
+  network error there surfaces in the audit log even when the chat reply
+  looked fine. A common cause is pasting a partial or non-Kindle
+  clippings file, which yields zero parsed books.
+- **An edit that didn't stick**: `PATCH /api/books/:id` is Approve-tier,
+  so a request without a valid operator Bearer token is rejected with 401
+  before the handler runs — book status/rating/notes corrections are made
+  from the dashboard, not by an autonomous agent. Once authenticated, it
+  returns 404 if the id doesn't exist and 400 for an invalid `status`
+  (only `reading`, `completed`, `abandoned`) or an out-of-range `rating`
+  (must be 1–5).
 
 ## Related
 

package/agent-assets/docs/features/lifestyle/receipts.md

@@ -18,14 +18,16 @@ tags:
   - lifestyle
   - receipts
   - mail
+  - integrations
 status: stable
 ask_examples:
   - Where are my receipts stored?
   - How do I save a receipt to my Obsidian vault?
   - What does the receipts table track?
+  - What receipts haven't I saved yet?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-17
+updated: 2026-05-28
 keywords:
   - receipt
   - invoice
@@ -33,6 +35,11 @@ keywords:
   - attachment
   - PDF
   - gmail receipts
+api_endpoints:
+  - GET /api/receipts
+  - GET /api/receipts/summary
+  - POST /api/receipts/:id/download
+  - PATCH /api/receipts/:id
 related:
   - features/lifestyle/reading
   - features/lifestyle/travel-bookings
@@ -43,41 +50,64 @@ related:
 
 ## In One Sentence
 
-Receipts are PDF / image attachments the Gmail observer flags as
-receipts or invoices; their metadata lives in the `receipts` SQLite
-table, and the agent can export the original file into your external
+Receipts are PDF / image attachments the Gmail observer detects while
+scanning your mail; their metadata lives in the `receipts` SQLite
+table, and the agent can save the original file into your external
 Obsidian vault on request.
 
-## What It Does
+## How Detection Works
 
-- The Gmail observer auto-detects receipt / invoice attachments while
-  scanning travel-booking and document mail.
-- Each detection inserts a row into the `receipts` table
-  (`provider_msg_id`, `attachment_id`, `filename`, `mime_type`,
-  `size_bytes`, `category`, `obsidian_path`, `saved_at`, `account_id`).
-- The agent surfaces summaries via the `/api/receipts` and
-  `/api/receipts/summary` HTTP routes.
-- On request, the agent downloads the attachment via
-  `POST /api/receipts/:id/download`, writes it into the external
-  Obsidian vault under `receipts/YYYY/MM/<merchant>-<date>.<ext>`, and
-  patches the row's `obsidian_path` / `saved_at` columns.
+The Gmail observer scans travel-booking emails for PDF / image
+attachments and retains other generic documents it finds. Each detected
+attachment inserts a row into the `receipts` table, keyed uniquely on
+`(account_id, provider_msg_id, attachment_id)` so re-scans are
+idempotent. Columns:
+
+- `category` — `document` or `travel` (nullable until classified)
+- `provider_msg_id`, `attachment_id`, `account_id` — locate the source
+  attachment in the unified mail registry
+- `filename`, `mime_type`, `size_bytes` — attachment metadata
+- `obsidian_path`, `saved_at` — `NULL` until you save the file to your
+  vault (see below)
+- `id`, `created_at` — row identity and detection time
 
 There is no Markdown context file for receipts; the durable record is
 the SQLite row plus the optional Obsidian copy.
 
+## Saving a Receipt to Your Vault
+
+Saving is a two-step flow — the download endpoint never writes to the
+vault by itself:
+
+1. The agent downloads the original bytes via
+   `POST /api/receipts/:id/download`, which streams the raw attachment
+   (resolved through the mail registry by `account_id`; oversized files
+   over 100 MB and orphaned rows with a null `account_id` are rejected).
+2. The agent writes the file into your **external** Obsidian vault — not
+   the primary management vault — under the convention
+   `receipts/YYYY/MM/<merchant>-<date>.<ext>` (e.g.
+   `receipts/2026/04/amazon-2026-04-12.pdf`), then records that path
+   with `PATCH /api/receipts/:id` (body `{"obsidianPath": "..."}`),
+   which also stamps `saved_at`.
+
+To reclassify a receipt, the agent PATCHes `{"category": "travel"}`
+(or `"document"`).
+
 ## Where in the Dashboard
 
 There is no dedicated tab today. Receipts surface inline when you ask
-for them in chat (e.g. "what receipts haven't I saved yet?"). The
-underlying API is documented in
+for them in chat (e.g. "what receipts haven't I saved yet?"). List and
+filter them with `GET /api/receipts` (`category`, `saved`, `limit`
+params) and pull totals from `GET /api/receipts/summary`. The full API
+is documented in
 `agent-assets/skills/gmail-lifestyle/references/receipts-api.md`
 (loaded by the `gmail-lifestyle` skill).
 
 ## Configuration
 
-The detection runs as part of the Gmail observer; see
-[Mail](../integrations/mail.md). The Obsidian save path follows the
-external vault convention `receipts/YYYY/MM/<merchant>-<date>.<ext>`.
+Detection runs as part of the Gmail observer; see
+[Mail](../integrations/mail.md). The save target follows the external
+vault convention `receipts/YYYY/MM/<merchant>-<date>.<ext>`.
 
 ## Related
 

package/agent-assets/docs/features/lifestyle/travel-bookings.md

@@ -11,20 +11,23 @@ aliases:
   - trains
 category: features
 summary: |
-  A lightweight log of trips, flights, hotels, and confirmation
-  numbers. The agent appends to it from confirmation emails or DMs.
+  A log of trips, flights, hotels, restaurants, and confirmation
+  numbers that the agent builds automatically from booking-confirmation
+  emails. The morning routine surfaces upcoming travel.
 section: lifestyle
 tags:
   - lifestyle
   - travel
   - mail
+  - integrations
 status: stable
 ask_examples:
-  - How do I log a flight?
+  - How does the agent track my flights and hotels?
   - Will the agent remind me about my upcoming trip?
+  - Where are my travel bookings stored?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
   - flight
   - hotel
@@ -33,27 +36,87 @@ keywords:
   - itinerary
   - trains
   - restaurants
+  - confirmation number
 related:
-  - features/lifestyle/travel-time
+  - features/integrations/mail
+  - features/lifestyle/receipts
+  - features/routines/morning-routine
+api_endpoints:
+  - /api/travel-bookings
+  - /api/travel-bookings/upcoming
+process_keys:
+  - gmail_classify
+  - routine.morning_routine
+ui_anchors:
+  - /trip
 ---
 
 # Travel Bookings
 
 ## In One Sentence
 
-A trip log the agent appends to from confirmation emails and DMs,
-referenced by the morning routine on travel days.
+A trip log the agent builds automatically from booking-confirmation
+emails, surfaced by the morning routine on travel days.
 
 ## What It Does
 
-- Captures trip dates, modes, and confirmation numbers.
-- Surfaces in the morning routine on the day of departure.
-- Cross-references the travel-time skill for door-to-airport math.
+The mail observer watches your connected mail accounts for booking
+confirmations from airlines, hotels, online travel agencies, restaurant
+reservation platforms, and rail/bus services. When a message is
+classified as travel, the daemon extracts the details and stores a row
+in the `travel_bookings` SQLite table:
 
-## Where in the Dashboard
+- **Type** — `flight`, `hotel`, `restaurant`, `train`, `bus`, or `other`.
+- **Provider** — e.g. the airline or hotel chain.
+- **Dates** — `start_date` and (where present) `end_date`.
+- **Confirmation number**, **amount**, and **currency**.
 
-Surfaces inline in chat and via the morning briefing on travel days.
+Each booking is keyed by its source message, so re-reading the same
+confirmation email never creates a duplicate row.
 
-## Related
+## How Bookings Get Created
 
-- [Travel Time](travel-time.md)
+Bookings are extracted from email only — there is no manual "log a
+flight" command or DM shortcut. To start capturing travel, connect a
+mail account (see [Mail](features/integrations/mail)) and let the
+classifier do the rest. The flow is:
+
+1. The mail poller fetches new messages.
+2. The classifier (`gmail_classify`, lite tier) tags travel
+   confirmations.
+3. The daemon parses the booking and inserts it into `travel_bookings`.
+
+## Where Bookings Surface
+
+- **Morning routine.** On travel days the morning routine
+  (`routine.morning_routine`) surfaces upcoming trips in your briefing.
+  A booking with a `start_date` within roughly the last 30 days (or in
+  the future) keeps the travel-aware briefing helpers active.
+- **Trip page.** The dashboard `/trip` page is the eventual home for an
+  itinerary timeline view. It is a placeholder while that view is built
+  — the underlying data already lives in the database and is reachable
+  via the API below.
+
+## API
+
+Read-only and status-update access (read endpoints are read-sensitive —
+they expose personal travel data; the PATCH endpoint follows the standard
+write-safety tier and requires approval):
+
+```bash
+# All bookings (optionally filter by type/status/date range)
+curl -s "http://localhost:8321/api/travel-bookings?type=flight&limit=20"
+
+# Upcoming only, sorted by start date
+curl -s "http://localhost:8321/api/travel-bookings/upcoming?limit=10"
+
+# Mark a booking completed
+curl -s -X PATCH "http://localhost:8321/api/travel-bookings/1" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "completed"}'
+```
+
+Filters on `GET /api/travel-bookings`: `type`
+(`flight|hotel|restaurant|train|bus|other`), `status`
+(`upcoming|completed|cancelled|all`), `from` / `to` (ISO date on
+`start_date`), and `limit` (1–200, default 50).