@aitne-sh/aitne 0.1.8 → 0.1.9

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-05-28
 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,32 @@ 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** — the agent updates an existing row via
+  `PATCH /api/books/:id`. 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 +85,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 +105,15 @@ 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` 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-05-28
 keywords:
   - flight
   - hotel
@@ -33,27 +36,86 @@ 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 autonomous; the
+PATCH endpoint follows the standard write-safety tier):
+
+```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).

package/agent-assets/docs/features/memory-files/agent-journal.md

@@ -1,7 +1,7 @@
 ---
 schema_version: 1
 slug: features/memory-files/agent-journal
-title: agent/journal.md
+title: journal/agent.md
 id: agent-journal
 aliases:
   - journal
@@ -10,96 +10,157 @@ aliases:
 category: features
 summary: |
   The agent's append-only log of decisions, retros, and judgement
-  calls. Distinct from Activity (which is action-shaped) — the journal
-  is reflection-shaped.
+  calls, at journal/agent.md. Distinct from Activity (which is
+  action-shaped) — the journal is reflection-shaped. Written by the
+  morning, evening, and weekly routines; the API enforces append-only.
 section: memory-files
 tags:
   - memory
   - journal
   - reflection
+  - routines
 status: stable
 ask_examples:
   - What is the agent journal?
   - Where does the agent log its own decisions?
   - How is the journal different from Activity?
+  - Why did journal/agent.md stop growing?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - journal
   - retros
   - decisions
   - reflection
+  - append-only
 related:
+  - features/routines/morning-routine
   - features/routines/evening-review
   - features/routines/weekly-review
   - features/operations/activity-and-conversations
+  - concepts/memory-model
+process_keys:
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.weekly_review
+context_files:
+  - journal/agent.md
 ui_anchors:
   - /connections/journal
   - /settings/journal
-context_files:
-  - agent/journal.md
 ---
 
-# agent/journal.md
+# journal/agent.md
 
-## In One Sentence
+## In one sentence
 
-`agent/journal.md` is the agent's own running diary — what it noticed,
+`journal/agent.md` is the agent's own running diary — what it noticed,
 what it tried, what it would do differently — appended (never
 rewritten) so a long timeline accumulates.
 
-## What It Does
+## What it is
 
 The journal is the place the agent writes about its own work in the
-first person. Each entry has:
-
-- A timestamp.
-- A short context line (which routine / conversation prompted it).
-- The reflection itself.
-
-Unlike Activity, the journal is opinion-shaped. The evening review
-adds the day's reflections; the weekly retro reads them back to
-look for patterns.
+first person. Unlike Activity — which is the action-shaped audit log
+of *what happened* — the journal is reflection-shaped: it captures
+*why*, *what surprised it*, and *what it would change*.
 
-## When It Runs / How It Is Triggered
+Each entry carries:
 
-- **Evening review** adds the largest chunk — what worked, what was
-  surprising, what felt off.
-- **Weekly review** appends a retro that quotes prior journal entries
-  to find a thread.
-- **In-the-moment** entries fire when the agent notices something
-  worth flagging during reactive work.
-
-## What It Outputs
-
-- An ever-growing append-only file at
-  `~/.personal-agent/context/agent/journal.md`.
-- A linked-from-roadmap section when an entry tied a project to a new
-  decision.
-
-## Where in the Dashboard
+- A timestamp (the routine stamps an `Appended at:` line).
+- A short context line — which routine or conversation prompted it.
+- The reflection itself.
 
-- **Connections → Journal** is the read view of the file.
-- **Settings → Journal** controls retention and which routines
-  contribute (currently always-on for evening / weekly).
+The file lives at `~/.personal-agent/context/journal/agent.md` and
+grows forever. Later routines read it back to look for patterns.
+
+## Who writes it, and when
+
+Three routines append to the journal — none ever rewrites it:
+
+- **Morning routine** (Stage B, `routine.morning_routine_journal`) is
+  the recurring daily writer. After the day's stages settle, the
+  daemon appends a one-paragraph audit-trail entry assembled from the
+  prior day's `agent_actions` — stage results, retry stats, anomalies.
+  This is the entry you'll see most often.
+- **Weekly review** (`routine.weekly_review`) appends the largest
+  structured block: a `## Weekly YYYY-Www` retro with *What worked*,
+  *What slipped on my side*, *System improvement ideas*, and agent-side
+  metrics. It quotes prior entries to find a thread.
+- **Evening review** (`routine.evening_review`) appends short
+  bookkeeping lines — for example a one-liner each time it bumps a
+  roadmap review forward, or a validation error if a roadmap write was
+  rejected. It does not write the bulk of the diary.
+
+In-the-moment notes can also land here when the agent flags something
+worth recording during reactive work.
+
+### Example entry
+
+```
+## Weekly 2026-W21
+> Appended at: 2026-05-25 21:40
+
+### What worked
+- Morning brief landed before the 09:00 standup three days running.
+### What slipped on my side
+- Missed the Friday PR-review trigger — webhook arrived during quiet hours.
+### System improvement ideas
+- Add Saturday to the Weekend day-type default so weekend pushes triage.
+### Metrics (agent side)
+- Agent plan rows completed: 12
+- Did-not-fire / failed rows: 1
+- Observations reviewed / ignored: 18 / 4
+```
+
+## Append-only — enforced, not just convention
+
+The journal is append-only at the API layer, not merely by prompt
+discipline. `journal/agent.md` is the sole entry in `CREATE_ONLY_PUT`:
+a `PUT` only succeeds if the file does not yet exist, and a `PATCH`
+must use `append` or `append_to_file` mode. A `replace` or `clear`
+PATCH is rejected outright, so a misbehaving (or prompt-injected) agent
+cannot destroy history. Writes go through the daemon context API
+(`PATCH /api/context/journal/agent`) — the agent has no direct
+`Edit`/`Write` access to the file.
+
+## Where in the dashboard
+
+- **Connections → Journal** (`/connections/journal`) is the read view
+  of the file.
+- **Settings → Journal** (`/settings/journal`) controls retention and
+  which routines contribute.
 
 ## Configuration
 
-There is no per-entry configuration. The file is plain Markdown — you
-can hand-edit, prune, or git-version it like any other context file.
+There is no per-entry configuration. The file is plain Markdown, so
+**you** (the human owner) can hand-edit, prune, or git-version it like
+any other context file — the API append-only guard applies only to the
+agent's own writes, not to you editing the file on disk.
 
-## When Something Goes Wrong
+## When something goes wrong
 
-- A journal that **stops growing** points at the evening review not
-  running. See [Evening Review](../routines/evening-review.md).
-- A journal that **looks duplicated** usually means a routine retried
-  after a fallback. The agent's own anti-duplicate check is best-effort,
-  not bulletproof — manual prune is fine.
+- **The journal stops growing.** This usually points at the morning
+  routine's Stage B (the daily writer) or the evening/weekly review not
+  running. See [Morning Routine](../routines/morning-routine.md) and
+  [Evening Review](../routines/evening-review.md).
+- **Entries look duplicated.** This usually means a routine retried
+  after a backend fallback. Because writes are append-only, a retry
+  can re-append rather than overwrite; the weekly review has an
+  idempotency check for its own section, but it is best-effort — a
+  manual prune is fine.
 
 ## Related
 
-- [Evening Review](../routines/evening-review.md) — the daily writer.
-- [Weekly Review](../routines/weekly-review.md) — the consumer.
-- [Activity](../operations/activity-and-conversations.md) — the
-  action-shaped audit log, distinct from the journal.
+- [Morning Routine](../routines/morning-routine.md) — the recurring
+  daily writer (Stage B).
+- [Weekly Review](../routines/weekly-review.md) — the largest retro,
+  and the main consumer that reads prior entries back.
+- [Evening Review](../routines/evening-review.md) — appends short
+  bookkeeping lines.
+- [Activity & Conversations](../operations/activity-and-conversations.md)
+  — the action-shaped audit log, distinct from the reflection-shaped
+  journal.
+- [Memory model](../../concepts/memory-model.md) — how the journal fits
+  the wider context vault.