@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/skills/external-services/SKILL.native.gemini.md

@@ -1,9 +1,8 @@
 ---
 name: external-services
-description: Load when an external-services surface is in scope (Google Calendar / Obsidian / GitHub / Skills CRUD / scheduling) and Google Calendar is in native mode bound to Gemini (`nativeBackend === "gemini"`). Calendar runs through the in-session Calendar connector your Gemini harness exposes directly; the daemon does not proxy Calendar. Other surfaces (Apple/Outlook Calendar, Obsidian, GitHub, scheduling, Skills CRUD) keep their direct routes.
+description: Load when an external-services surface is in scope and Google Calendar is in native mode bound to Gemini (`nativeBackend === "gemini"`). Calendar runs via the Gemini Calendar connector; daemon does not proxy. Obsidian, GitHub, scheduling, Skills CRUD keep direct routes.
 allowed-tools:
   - Bash(curl *)
-  - Bash(jq *)
   - Read
 ---
 
@@ -34,7 +33,7 @@ and the `<integration-routing-table>` block in the session preamble.
 
 ## Source of Truth (READ FIRST)
 
-Same files as the direct-mode body — `rules/management.md` →
+Same files as the direct-mode body — `policies/management.md` →
 `## Source of Truth` and `~/.personal-agent/integrations.md` →
 `## Note Sources`. If Schedule != Google Calendar, route through the
 provider-specific direct route (`/api/apple-calendar/*` or
@@ -125,7 +124,7 @@ materialised event to `/api/observations` per the section below.
 ## Apple Calendar (iCloud CalDAV) — direct, unchanged
 
 Use `/api/apple-calendar/*` per the direct-mode body if
-`rules/management.md` Schedule = Apple Calendar.
+`policies/management.md` Schedule = Apple Calendar.
 <!-- /service:apple-calendar -->
 
 ---
@@ -171,10 +170,10 @@ curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old
 
 ```bash
 curl -s http://localhost:8321/api/github/repos
-curl -s "http://localhost:8321/api/github/pulls?state=open"
+curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open"
 curl -s -X POST http://localhost:8321/api/github/pulls/comment \
   -H 'Content-Type: application/json' \
-  -d '{"owner": "user", "repo": "repo", "pullNumber": 42, "body": "LGTM"}'
+  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}'
 ```
 <!-- /service:github -->
 

package/agent-assets/skills/external-services/references/calendar-apple.md

@@ -0,0 +1,97 @@
+---
+kind: reference
+name: calendar-apple
+description: Apple Calendar (iCloud CalDAV) reference — list/get/create/update/delete with recurring-instance gotchas, app-specific-password setup probe, no proactive notifications. Stripped when `apple_calendar` is not configured.
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV)
+
+Use this section **only when `policies/management.md` Schedule = Apple Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+The route shape mirrors `/api/calendar/*` so prose patterns transfer: list → get → patch / create / delete. Differences are flagged below.
+
+### Probe configuration before first use
+```bash
+curl -s http://localhost:8321/api/apple-calendar/status
+# → { "configured": bool, "available": bool }
+```
+- `configured: false` → user has not entered Apple ID + app-specific password yet. Tell the user to open the dashboard's Apple Calendar card (Connections page) and paste a password from `appleid.apple.com` → Sign-In and Security → App-Specific Passwords. **Do not try to read or write events** until `available: true`.
+- `configured: true, available: false` → credentials are stored but iCloud rejected the last connection. Surface verbatim; common cause is the user revoked the app-specific password.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events?date=today&days=3"
+```
+Same query params as Google: `date` (`YYYY-MM-DD` or `today`), `days` (max 90). Returns `{ events: [...] }` with the same JSON shape used by the Google route — `id`, `summary`, `start`, `end`, `location`, `description`, `allDay`, `status`, plus two Apple-specific fields:
+- `recurring` (bool) — true for any event in a recurring series.
+- `recurrenceId` (string|null) — populated for an expanded instance of a series.
+
+For a recurring instance the `id` is `<UID>__<RECURRENCE-ID>` so you can address a specific occurrence.
+
+**Timezones**: dateTime values are emitted in UTC (`Z` suffix). Convert to the user's local timezone before showing them.
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events/<id>"
+```
+Always GET before PATCH so you see the current summary/start/end.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/events \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-26T14:00:00+09:00", "end": "2026-04-26T15:00:00+09:00"}'
+```
+Optional: `description`, `location`. **[Apple only]** `attendees`, `reminders`, `recurrence`, `visibility` from the Google shape are **rejected** — the Apple schema is `.strict()`, so including any of them fails the whole request with `400 validation_error` and no event is created (the same applies to PATCH). iCloud invitations and reminder defaults belong to the user's Apple ID and the agent should not author them. If a user asks for those, tell them and stop — do not include the fields in the request.
+
+### Update event (write — Autonomous)
+```bash
+curl -s -X PATCH http://localhost:8321/api/apple-calendar/events/<id> \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-26T15:00:00+09:00", "end": "2026-04-26T16:00:00+09:00"}'
+```
+
+**[Apple only] Recurring-event editing semantics — read before writing**
+- A composite id (one whose suffix matches `__YYYY-MM-DD…`) addresses **one occurrence** of a series. PATCH/DELETE on it returns `501 recurring_instance_unsupported`. To move a single occurrence the user must edit it from Calendar.app.
+- A bare id whose GET returned `recurring: true` is the **series master**. PATCH on the master shifts the **entire series** (every future occurrence moves), and DELETE removes the entire series. Confirm with the user that they intend a series-level edit before issuing the call — agents have historically read "PATCH this event's start" as a single-instance reschedule, which is wrong here.
+- A bare id with `recurring: false` is a normal one-off event — PATCH/DELETE behave as usual.
+- `summary`, `start`, and `end` may be updated independently. Toggling all-day-ness (`YYYY-MM-DD` ↔ `…T…Z`) requires providing **both** `start` and `end` in the same PATCH; the codec rejects partial all-day toggles with `400 validation_error`.
+- Time strings must include a TZ offset (`Z` or `±HH:MM`); naked ISO without offset returns `400 validation_error` — do not interpret a user-stated time as local without an explicit offset.
+
+### Delete event (write — Autonomous)
+```bash
+curl -s -X DELETE http://localhost:8321/api/apple-calendar/events/<id>
+```
+Same recurring semantics as PATCH (see the rules block above).
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/apple-calendar/calendars
+# → { "calendars": [{ id, summary, description, primary }, ...] }
+```
+The `id` is an opaque CalDAV URL. The user's primary calendar is marked `primary: true`. To change which calendar create/list reads, see the dashboard Apple Calendar card.
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-26T09:00:00Z", "timeMax": "2026-04-26T18:00:00Z"}'
+```
+**[Apple only]** Free-busy is derived from `listEvents` — events with `status: "cancelled"` are excluded. `calendarIds` is ignored (the primary calendar is the only target).
+
+### Apple Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape. Fix and retry. |
+| 401 | `auth_failed` | iCloud rejected the credentials. Tell the user to refresh the app-specific password in the dashboard. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 501 | `recurring_instance_unsupported` | The id targets a single occurrence of a recurring series — see the PATCH/DELETE notes above. |
+| 502 | `apple_calendar_error` | Upstream iCloud / CalDAV error. `message` carries the wire text. |
+| 503 | `apple_calendar_not_configured` | Credentials missing or last connection failed. Run the status probe above. |
+
+### Known gap: no proactive notifications
+
+The hourly polling pivot (`schedule.approaching` events, observation deltas) only fires for Google Calendar today. With Apple Calendar selected, on-demand DM queries work but the agent will not proactively warn about an imminent event — the user's own iOS / macOS Calendar.app notifications fill that gap.
+<!-- /service:apple-calendar -->

package/agent-assets/skills/external-services/references/calendar-google.md

@@ -0,0 +1,72 @@
+---
+kind: reference
+name: calendar-google
+description: Google Calendar direct-mode reference — list/get/create/update/delete events, list calendars, free-busy. ATTENDEES PATCH replaces the whole list. Stripped by the integration-mode filter when `google_calendar !== "direct"`.
+---
+
+<!-- service:calendar -->
+## Calendar
+
+Google Calendar proxy. Operates on the user's primary calendar (configurable via `calendarId` param).
+
+**Timezone rule**: Always include a TZ offset in `start`/`end` dateTime values (e.g. `-04:00`). All-day events use `YYYY-MM-DD` (no TZ needed).
+
+**Event status**: GET returns deleted events with `status: "cancelled"` (200, not 404). Always check `status` before acting. The list endpoint automatically excludes cancelled events.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/events?date=today&days=3"
+```
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/calendar/events/abc123eventid"
+```
+**Always GET before PATCH** to see current state and attendees.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST "http://localhost:8321/api/calendar/events" \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-02T14:00:00-04:00", "end": "2026-04-02T15:00:00-04:00"}'
+```
+Optional: `description`, `location`, `reminders`, `recurrence`, `attendees`, `visibility`. All-day: `YYYY-MM-DD`. Attendees: add `?sendUpdates=all` to notify. RRULE: `RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR`.
+
+### Update event (write — Autonomous; commonly on the starter denylist)
+```bash
+curl -s -X PATCH "http://localhost:8321/api/calendar/events/abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-02T15:00:00-04:00", "end": "2026-04-02T16:00:00-04:00"}'
+```
+For recurring events, use the instance ID to update a single occurrence — never PATCH the master.
+
+**ATTENDEES WARNING**: PATCH with `attendees` **replaces the entire list** — it does NOT append. To add one attendee: (1) GET, (2) copy existing, (3) add new, (4) PATCH full list.
+
+### Delete event (write — Autonomous; default starter denylist denies it)
+```bash
+curl -s -X DELETE "http://localhost:8321/api/calendar/events/abc123"
+```
+Add `?sendUpdates=all` to notify attendees. Do NOT PATCH a cancelled event.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/calendars
+```
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-11T09:00:00-04:00", "timeMax": "2026-04-11T18:00:00-04:00"}'
+```
+
+### Calendar error envelope (direct mode)
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape (e.g. missing `start`/`end`, malformed RRULE). Fix and retry. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 410 | `integration_delegated` | Calendar flipped to delegated mode mid-session. This skill body is direct-only — re-read `integrations.md` and use `POST /api/integrations/google_calendar/exec` (cross-backend task mode) or your session backend's native Calendar MCP (the same-backend variant) instead. |
+| 502 | `calendar_error` | Upstream Google API error — `message` carries the API's text. Surface verbatim; do not retry unless clearly transient. |
+| 503 | `calendar_not_configured` | Direct OAuth credentials are missing or the user has disabled Calendar in settings. Tell the user and stop. |
+<!-- /service:calendar -->

package/agent-assets/skills/external-services/references/calendar-outlook.md

@@ -0,0 +1,36 @@
+---
+kind: reference
+name: calendar-outlook
+description: Outlook Calendar reference (Microsoft Graph) — read-only on-demand. Same query shape as Google. Stripped when `outlook_calendar` is not configured.
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph)
+
+Use this section **only when `policies/management.md` Schedule = Outlook Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+v1 is **read-only and on-demand** — there is no Outlook calendar poller, so `schedule.approaching` events do not fire for Outlook calendars (the user's own Outlook clients fill that gap). Write surfaces (create / update / delete) are deferred. If the user asks the agent to schedule or change an Outlook event, tell them you can read the calendar but must defer the write to them.
+
+OAuth is **shared with Outlook Mail** via the same MSAL cache row (`mail:outlook:<accountId>`) — if Outlook Mail is configured `direct` and authenticated, calendar reads succeed with no second consent.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/outlook/events?date=today&days=3"
+```
+Same query params as Google (`date`: `YYYY-MM-DD` or `today`; `days`: 1–90; optional `calendarId`). Returns `{ events: [...], accountId }`.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/outlook/calendars
+```
+Returns `{ calendars: [...], accountId }`. The user's primary calendar is marked `primary: true`.
+
+### Outlook Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | bad query | Malformed `date` or `days` value. |
+| 502 | `calendar_error` | Upstream Microsoft Graph error — `message` carries wire text. |
+| 503 | `outlook_not_configured` | No authenticated Outlook account. Direct OAuth credentials missing. |
+| 503 | `outlook_calendar_disabled` | The user toggled Outlook Calendar off in Settings → Calendar. Tell the user and stop. |
+<!-- /service:outlook-calendar -->

package/agent-assets/skills/external-services/references/github.md

@@ -0,0 +1,17 @@
+---
+kind: reference
+name: github
+description: GitHub direct-mode reference — list repos, list PRs, comment on a PR. Autonomous tier. Stripped when `github` is not configured.
+---
+
+<!-- service:github -->
+## GitHub
+
+```bash
+curl -s http://localhost:8321/api/github/repos                              # list watched repos
+curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open" # list PRs
+curl -s -X POST http://localhost:8321/api/github/pulls/comment \
+  -H 'Content-Type: application/json' \
+  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}' # comment — Autonomous
+```
+<!-- /service:github -->

package/agent-assets/skills/external-services/references/obsidian.md

@@ -0,0 +1,49 @@
+---
+kind: reference
+name: obsidian
+description: External Obsidian vault CRUD — separate from the agent's primary management vault. Routed via /api/obsidian/*. Stripped when `obsidian` is not configured.
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault)
+
+**Scope**: this skill targets a **separate** Obsidian vault the user maintains
+alongside this app — e.g. a personal knowledge base. It is **not** the agent's
+own primary management store. The agent's primary files (`state/today.md`,
+`plans/roadmap.md`, `projects/`, `rules/`, `routines/`, `user/`, `agent/`, …) live
+in the primary vault and are reached via `/api/context/*` (see the `context`
+skill). **Never** use this skill to read or write the primary vault.
+
+Use this skill when the user asks the agent to look up, append to, or create
+notes inside their external knowledge vault — never for the agent's own
+working state.
+
+Output language: external-vault writes are Policy C — see `<output_language_policy>`. Preserve verbatim any path / file-name patterns the user has established.
+
+Full CRUD over the external vault. Requires the Obsidian app running (the
+CLI proxies through it). Omit `.md` extension from paths. All writes are
+Autonomous; the daemon does not DM the owner before/after the call. Call
+`POST /api/notify` yourself when the user would want to know.
+
+```bash
+curl -s http://localhost:8321/api/obsidian/status                            # external vault availability
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10" # search external vault
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06    # read external note
+curl -s -X POST http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'    # create external note (fails if exists)
+curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
+  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'       # create-or-overwrite external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'   # append to external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'   # append to external daily note
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old      # delete from external vault (moves to trash)
+```
+**Endpoint choice**: Read → GET, Create-only → POST, Edit → PUT, Append → PATCH.
+
+If the user's request is really about the agent's own state (today, roadmap,
+projects, journal, rules, routines, user profile), switch to the `context`
+skill and the `/api/context/*` endpoints instead.
+<!-- /service:obsidian -->

package/agent-assets/skills/external-services/references/skills-crud.md

@@ -0,0 +1,27 @@
+---
+kind: reference
+name: skills-crud
+description: Dashboard-shaped CRUD for user-authored skills under ~/.personal-agent/skills/. Built-in skills are read-only (403).
+---
+
+## Skills Management
+
+User-authored skills: `~/.personal-agent/skills/{slug}/SKILL.md`. Built-in skills are read-only (403). Slug: lowercase kebab-case `[a-z0-9][a-z0-9-]*`, 1–64 chars.
+
+```bash
+curl -s http://localhost:8321/api/skills                                            # list all
+curl -s http://localhost:8321/api/skills/todo-digest                                # read one
+curl -s -X POST http://localhost:8321/api/skills \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "todo-digest", "description": "Summarize today.md", "content": "# TODO Digest\n...", "allowedTools": ["Bash(curl *)", "Read"]}'
+curl -s -X PUT http://localhost:8321/api/skills/todo-digest \
+  -H 'Content-Type: application/json' -d '{"description": "New description"}'      # update
+curl -s -X DELETE http://localhost:8321/api/skills/todo-digest                      # delete
+```
+Always `GET /api/skills` before creating (check name collisions). **Omit frontmatter** from `content` — the API injects it.
+
+The description is the **only** routing signal the SDK uses to pick a
+skill — keep it under 280 chars and make the trigger surface
+distinct from every other skill in the manifest. Slug grammar is
+strict: `[a-z0-9][a-z0-9-]*[a-z0-9]` or `[a-z0-9]` (single char),
+1-64 chars total. PUT rejects collisions with built-in slugs.

package/agent-assets/skills/gmail-lifestyle/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: gmail-lifestyle
+description: Load when the user mentions receipts / expenses / flights / hotels / trains / a booking — Gmail-observer-derived travel bookings and receipt save-to-external-vault both live here.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Gmail Lifestyle — travel bookings, receipts
+
+This skill merges two closely-related surfaces that both depend on
+data the daemon's **Gmail observer** has scanned: travel bookings and
+receipt attachments saved into the user's external Obsidian vault.
+
+It is conditionally loaded — see the manifest predicate
+`gmailLifestyleActive(db)` / `gmailLifestyleActiveForDm(db, msg)`
+in `packages/daemon/src/core/skills-manifest.ts`. Routines load it
+when there is fresh-or-pending data; DM events also load it on
+trigger phrases (`receipt`, `expense`, `flight`, `train`, plus the
+user's primary-language equivalents — the predicate handles both the
+structured triggers and the message-text triggers).
+
+Output language: Policy C for user-facing summaries — see
+`<output_language_policy>`. Path patterns and external API field
+names stay verbatim.
+
+---
+
+## Travel bookings
+
+The daemon's Gmail observer detects booking confirmation emails from
+airlines, hotels, OTAs, restaurant reservation platforms, and rail
+services. Data is stored in the `travel_bookings` SQLite table.
+
+### When to use
+
+- **Morning routine** — surface upcoming travel / bookings within the
+  next 7 days inside today.md `## Travel & Reservations`.
+- **Evening review** — report newly detected bookings (today's
+  `createdAt`).
+- **User asks about trips / reservations** — query bookings and
+  summarize.
+- **Pre-trip reminders** — surface upcoming travel the day before
+  departure.
+
+### Workflow
+
+1. Fetch upcoming bookings from `/api/travel-bookings/upcoming`.
+2. For morning routine, highlight bookings within the next 7 days.
+3. For evening review, check for newly detected bookings (today's
+   `createdAt`).
+
+### API
+
+Full `/api/travel-bookings` reference (GET filter + upcoming +
+PATCH status) is in the dedicated reference below.
+
+{{> ref:travel-bookings-api }}
+
+### Formatting
+
+Morning routine — today.md:
+
+```
+## Travel & Reservations
+Upcoming flight: United to SFO (May 15) — confirmation ABC123
+Hotel: Marriott SF (May 15-17) — confirmation XYZ789
+Restaurant: OpenTable reservation tonight 19:00
+```
+
+Omit the section when no upcoming bookings within 7 days.
+
+Evening review:
+
+```
+## New Bookings Detected
+- United flight: May 15, confirmation ABC123, $350
+```
+
+Booking type display names: flight → Flight, hotel → Hotel,
+restaurant → Restaurant, train → Train, bus → Bus, other →
+Reservation.
+
+---
+
+## Receipts
+
+The daemon's Gmail observer scans travel-booking emails for PDF /
+image attachments and can retain previously detected generic
+documents. Attachment metadata is stored in the `receipts` SQLite
+table. Actual files are downloaded on demand and can be saved to the
+user's **external Obsidian vault**.
+
+### Primary vault vs external vault — read first
+
+> **WARNING — do not confuse vaults.** Receipts save into the
+> **external** Obsidian vault (user's personal knowledge base reached
+> via `/api/obsidian/*`), **not** the primary management store
+> reached via `/api/context/*`. The agent's own state files
+> (`state/today.md`, `plans/roadmap.md`, `projects/*`, `user/*`, `rules/*`,
+> `routines/*`, `agent/*`) live in the primary store and must
+> **never** receive receipt attachments. See the
+> `external-services` skill's obsidian reference for the external
+> vault's full CRUD surface.
+
+`receipts.obsidianPath` is a path **inside the external vault**.
+
+### When to use
+
+- **User asks about receipts** — list detected receipts, check save
+  status.
+- **Tax preparation season** — generate annual receipt list, save
+  unsaved receipts.
+- **Monthly / yearly review** — report on receipt-collection
+  completeness.
+
+### Workflow
+
+1. Fetch the receipt list from `/api/receipts`.
+2. To save a receipt to the external Obsidian vault:
+   a. Download via `POST /api/receipts/:id/download` (binary stream).
+   b. Save to the vault via `POST /api/obsidian/notes` (see the
+      `external-services` obsidian reference for path conventions).
+   c. Update the receipt record with the vault-relative path via
+      `PATCH /api/receipts/:id` `{"obsidianPath": "..."}`.
+3. For tax preparation, filter by date range and category.
+
+### API
+
+Full `/api/receipts` reference (GET filter + summary + download +
+PATCH) plus the external-vault save convention
+(`receipts/YYYY/MM/<merchant>-<date>.<ext>`) is in the dedicated
+reference below.
+
+{{> ref:receipts-api }}
+
+---
+
+## When NOT to act
+
+- If the predicate gates above are false (no fresh bookings, no
+  unsaved receipts, no trigger phrase), this skill is not loaded —
+  the manifest layer handles that decision. If you see this body
+  anyway, it means the predicate matched something concrete; do not
+  guess that the user wants travel / commute / receipt work without
+  evidence in the conversation or the DB.
+- Do not write receipts to `/api/context/*` — that targets the
+  primary management vault. See the §"Primary vault vs external
+  vault" warning above.
+- Bulk receipt operations (save-all, reclassify-all) need explicit
+  user confirmation; surface the count and criteria first.

package/agent-assets/skills/gmail-lifestyle/references/receipts-api.md

@@ -0,0 +1,93 @@
+---
+kind: reference
+name: receipts-api
+description: /api/receipts reference — list / filter, download, save-to-external-Obsidian-vault, reclassify, and summary endpoints for Gmail-observer-flagged attachments.
+---
+
+# `/api/receipts` reference
+
+The daemon's Gmail observer scans travel-booking emails for PDF /
+image attachments and can retain previously detected generic
+documents. Attachment metadata is stored in the `receipts` SQLite
+table. Actual files are downloaded on demand and saved to the user's
+**external Obsidian vault** (NOT the primary management vault — see
+the `## Receipts` section of the parent skill for the vault-routing
+warning).
+
+## GET /api/receipts
+
+```bash
+# All receipts
+curl -s "http://localhost:8321/api/receipts?limit=50"
+
+# Unsaved receipts only
+curl -s "http://localhost:8321/api/receipts?saved=false"
+
+# Filter by category
+curl -s "http://localhost:8321/api/receipts?category=document"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `category` | string | — | document, travel |
+| `saved` | boolean | — | true = saved to Obsidian, false = not yet saved |
+| `limit` | number | 50 | Max results (1–200) |
+
+Response:
+
+```json
+{
+  "receipts": [
+    {
+      "id": 1,
+      "providerMsgId": "18f...",
+      "attachmentId": "ANGj...",
+      "filename": "receipt.pdf",
+      "mimeType": "application/pdf",
+      "sizeBytes": 45000,
+      "category": "document",
+      "obsidianPath": null,
+      "savedAt": null,
+      "createdAt": "2026-04-12T10:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+## GET /api/receipts/summary
+
+```bash
+curl -s "http://localhost:8321/api/receipts/summary"
+```
+
+Returns counts: `{ total, saved, unsaved, byCategory: [{ category, count }] }`.
+
+## POST /api/receipts/:id/download
+
+```bash
+curl -s -X POST "http://localhost:8321/api/receipts/1/download" -o receipt.pdf
+```
+
+Binary stream of the original attachment.
+
+## PATCH /api/receipts/:id
+
+```bash
+# Mark as saved to external Obsidian vault
+curl -s -X PATCH "http://localhost:8321/api/receipts/1" \
+  -H "Content-Type: application/json" \
+  -d '{"obsidianPath": "receipts/2026/04/amazon-receipt.pdf"}'
+
+# Reclassify a receipt
+curl -s -X PATCH "http://localhost:8321/api/receipts/1" \
+  -H "Content-Type: application/json" \
+  -d '{"category": "travel"}'
+```
+
+## External-vault save convention
+
+Save receipts to `receipts/YYYY/MM/<merchant>-<date>.<ext>` inside
+the external Obsidian vault.
+
+Example: `receipts/2026/04/amazon-2026-04-12.pdf`.

package/agent-assets/skills/gmail-lifestyle/references/travel-bookings-api.md

@@ -0,0 +1,75 @@
+---
+kind: reference
+name: travel-bookings-api
+description: /api/travel-bookings reference — filter / upcoming / PATCH status for Gmail-observer-detected flight, hotel, train, restaurant, and bus reservations.
+---
+
+# `/api/travel-bookings` reference
+
+The daemon's Gmail observer detects booking confirmation emails from
+airlines, hotels, OTAs, restaurant reservation platforms, and rail
+services. Data is stored in the `travel_bookings` SQLite table.
+
+## GET /api/travel-bookings
+
+```bash
+# All bookings
+curl -s "http://localhost:8321/api/travel-bookings?limit=20"
+
+# Filter by type
+curl -s "http://localhost:8321/api/travel-bookings?type=flight"
+
+# Upcoming only
+curl -s "http://localhost:8321/api/travel-bookings?status=upcoming"
+
+# Date range
+curl -s "http://localhost:8321/api/travel-bookings?from=2026-04-01&to=2026-05-01"
+```
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | string | — | flight, hotel, restaurant, train, bus, other |
+| `status` | string | all | upcoming, completed, cancelled, all |
+| `from` | ISO date | — | Bookings with start_date on or after |
+| `to` | ISO date | — | Bookings with start_date before |
+| `limit` | number | 50 | Max results (1–200) |
+
+Response:
+
+```json
+{
+  "bookings": [
+    {
+      "id": 1,
+      "type": "flight",
+      "provider": "United",
+      "destination": null,
+      "startDate": "2026-05-15T10:30:00Z",
+      "endDate": null,
+      "confirmationNumber": "ABC123",
+      "amount": 350,
+      "currency": "USD",
+      "status": "upcoming",
+      "providerMsgId": "18f...",
+      "createdAt": "2026-04-12T10:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+## GET /api/travel-bookings/upcoming
+
+Convenience endpoint, sorted by start date.
+
+```bash
+curl -s "http://localhost:8321/api/travel-bookings/upcoming?limit=10"
+```
+
+## PATCH /api/travel-bookings/:id
+
+```bash
+curl -s -X PATCH "http://localhost:8321/api/travel-bookings/1" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "completed"}'
+```