librian 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.2.0] - 2026-11-08
+
+### Added
+
+- **`changes` tool.** A fifth tool per docs folder (`team__changes`) lists the
+  blocks added, changed or removed since the session start, or since a
+  `since` time you pass (ISO 8601, local time when it has no zone), with their
+  current `path:start-end`. Pass the `As of` time of one call as `since` to get
+  only what changed after it. Added and removed files are one line each; the
+  output stays within the byte limit and continues with `More: offset=N`.
+- **A history of block hashes.** `~/.librian/history.db` (Node's built-in
+  `node:sqlite`, no new dependency) keeps each docs file's heading lines and a
+  short hash of every block, never the text, for 30 days. It is shared by all
+  sessions, survives restarts and is never written inside a docs folder. A
+  running server also refreshes it every 5 minutes and stops by itself when its
+  parent process is gone. If the file cannot be used or was deleted while a
+  server runs, only `changes` reports it.
+
+### Changed
+
+- **Uninstall also removes `history.db`.** The confirmation says so; docs
+  folders and the catalog are kept.
+- **Server shutdown has one path.** stdin end, a broken stdout, an uncaught
+  exception, SIGINT and SIGTERM all stop the timer and the history, then close
+  the server.
+
 ## [0.1.2] - 2026-11-08
 
 ### Changed

package/README.md

@@ -86,8 +86,8 @@ If `librian` is already registered there with a different command, Apply replace
 ### Runtime
 
 librian installs itself with `npm install --prefix ~/.librian/runtime librian`, so the registered server does not depend on `npx` or a download at session start.
-**Install**, **Check for updates** (asks npm only when you choose it) and **Update to X** do what they say; **Uninstall** removes the runtime folder and offers to unregister the services first.
-Docs entries are kept.
+**Install**, **Check for updates** (asks npm only when you choose it) and **Update to X** do what they say; **Uninstall** removes the runtime folder and `history.db` and offers to unregister the services first.
+Docs folders and the catalog are kept.
 
 ### Where things live
 
@@ -95,12 +95,13 @@ Docs entries are kept.
 | --- | --- |
 | `~/.librian/catalog.json` | Your entries and which services are registered. No secrets. |
 | `~/.librian/runtime/` | The installed package. |
+| `~/.librian/history.db` | What `changes` compares against: per docs file, its heading lines and a short hash of each block. No docs text is stored. You can delete it; the next session starts a new history. |
 
 Set `LIBRIAN_HOME` to use another folder. When it is not the default, the registered command carries it along.
 
 ## What the AI sees
 
-One server, four tools per docs folder, prefixed with the entry name: for an entry `team` the tools are `team__list`, `team__outline`, `team__read` and `team__search`.
+One server, five tools per docs folder, prefixed with the entry name: for an entry `team` the tools are `team__list`, `team__outline`, `team__read`, `team__search` and `team__changes`.
 Each tool description names its folder, and the server instructions list the folders with their file counts. A folder that is missing on disk offers no tools and is marked `unavailable`.
 
 | Tool | Input | Returns |
@@ -109,6 +110,7 @@ Each tool description names its folder, and the server instructions list the fol
 | `outline` | `ref` | Headings of a file or of one section, each with its line range and size. |
 | `read` | `ref` | The text of a whole file, one section or a line range. |
 | `search` | `query`, `prefix?`, `limit?`, `offset?` | Blocks that contain every word of the query, each with its `path:start-end`, ancestor headings, size, number of hits and a one-line excerpt. |
+| `changes` | `since?`, `prefix?`, `offset?` | Blocks added, changed or removed since the session start (or `since`), each with its current `path:start-end`, ancestor headings and size. Added and removed files are one line each. |
 
 A typical session: `search` or `list` to find the file, `outline` to see its headings, `read` one section.
 
@@ -133,6 +135,29 @@ When you pass a reference to another agent or write it into a document, prefer `
 - Every word must appear in the same block, a heading plus the text up to the next heading. Ancestor headings count, so a block under `## Release rail` matches `release deploy` even if only `deploy` is in its text.
 - Results are ordered by words found in headings, then a relevance score that favours short, focused blocks over long ones that merely repeat a word (BM25), then path and line. The `N hits` on a row is the plain match count.
 
+### Changes
+
+`changes` tells an agent what moved in the docs while it worked, so it re-reads only that.
+
+```
+Changes since 2026-11-08T09:00:12.034+09:00 (session start) · 3 files · 4 blocks
+As of 2026-11-08T11:30:05.678+09:00. Pass this as `since` to see only later changes.
+
+guide/setup.md
+  changed  guide/setup.md:41-58 · ## 3. Setup › ### 3.3 Pipes · 1.2K
+  added    guide/setup.md:59-70 · ## 3. Setup › ### 3.4 Sockets · 640B
+  removed  ## 3. Setup › ### 3.5 Legacy
+team/decisions.md · added · 3.1K
+old/notes.md · removed
+```
+
+- `since` is an ISO 8601 time with or without a zone (`2026-11-08T09:00:00+09:00`, `2026-11-08T09:00`; no zone means local time). Leave it out for the session start. A malformed value is an error with an example.
+- Pass the `As of` time back as `since` to see only what changed after that call: no gaps, no repeats. While paging with `offset`, keep the same `since`.
+- Blocks are paired by their heading line, in order, so a block that only moved down the file is not reported, repeated headings pair up in order, a renamed heading is `removed` plus `added`, and an edit that was undone is not reported. A block is a heading plus the text up to the next heading, the same unit `search` returns.
+- Output stays within the byte limit and is cut between files (`More: offset=N`). A file whose own list does not fit becomes one line: `guide/setup.md · changed · 34 of 40 blocks; outline it`.
+- A `since` older than the first record says where the history starts (`History starts …`) and uses that.
+- The record is kept in `~/.librian/history.db` for 30 days, across restarts and shared by every session, and a running server also refreshes it every 5 minutes so the times stay close to the real edits. If the file cannot be used, only `changes` reports it.
+
 ### Limits and continuing
 
 Each response stays within the entry's byte limit (16000 by default, roughly 4–5 thousand tokens of Korean text).
@@ -140,7 +165,7 @@ When something is bigger, the response says how to get the rest:
 
 - `read` of a large file returns its outline; `read` of a large section with subsections returns the section's own text plus the subsection outline.
 - `read` of a large section without subsections returns the first page and ends with `Continue: path:next-end`. Pass that reference to `read` to get the next page.
-- `search` and `list` end with `More: offset=N` or a hint to narrow with `prefix`.
+- `search`, `changes` and `list` end with `More: offset=N` or a hint to narrow with `prefix`.
 
 ## Advanced: one folder, registered by hand