librian 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,13 +4,50 @@ 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
+
+- **Search ranks by BM25 instead of hit count.** After the headings rule, blocks
+  are ordered by a BM25 score (no IDF), so a short, exact block is no longer
+  pushed down by a long block that repeats the words many times. The `N hits`
+  on a result row is unchanged.
+- **Generic examples.** The README, the `list` tool description and the usage
+  text use neutral example names (`guide/api`, `team`). Behaviour is unchanged.
+
 ## [0.1.1] - 2026-11-08
 
 ### Added
 
 - **`librian add [<folder>]`.** Adds a docs folder without opening the menu:
   run it inside the docs folder, or pass the path. It counts the markdown
-  files, asks `Add it as "akms_docs"? (Y/n)` and adds the entry. It refuses
+  files, asks `Add it as "team_docs"? (Y/n)` and adds the entry. It refuses
   your home folder and a drive root (exit code 2), says `Already added as …`
   (exit code 0) for a folder that is already there, and adds nothing when the
   input ends.
@@ -70,5 +107,5 @@ First release.
   `~/.librian/catalog.json`; `LIBRIAN_HOME` moves both.
 - **One server for all folders.** `librian serve --catalog` is what the AI
   services run: it offers the four tools for each entry, prefixed with the
-  entry name (`akms__read`). `librian serve --root <folder>` serves a single
+  entry name (`team__read`). `librian serve --root <folder>` serves a single
   folder with unprefixed tools, for registering by hand.

package/README.md

@@ -40,22 +40,22 @@ Choose an entry to **Edit**, **Check** (file count, total size, largest files) o
 **Add docs folder** asks for one thing, the folder, and then adds it:
 
 ```
-? Docs folder › D:\workspace\projects\akms\akms.docs
+? Docs folder › D:\workspace\projects\team\team.docs
   107 markdown files · 4.1M
-? Add it as "akms_docs"? (Y/n)
-✔ Added akms_docs. Open a new session to use akms_docs__read and the other tools.
+? Add it as "team_docs"? (Y/n)
+✔ Added team_docs. Open a new session to use team_docs__read and the other tools.
 ```
 
-A folder that does not exist is refused with the reason and asked again with what you typed. A folder that is already added says `Already added as "akms".` and takes you to that entry. A folder without markdown files gets a warning and the question defaults to No. Esc saves nothing. The entry gets the default name, no Exclude and the default Max bytes; change them with **Edit** on the entry.
+A folder that does not exist is refused with the reason and asked again with what you typed. A folder that is already added says `Already added as "team".` and takes you to that entry. A folder without markdown files gets a warning and the question defaults to No. Esc saves nothing. The entry gets the default name, no Exclude and the default Max bytes; change them with **Edit** on the entry.
 Counting stops at 5,000 files or after 2 seconds and shows `5000+ files`, so picking a huge folder by mistake does not hang the menu.
 
 An entry has:
 
 | Field | Meaning |
 | --- | --- |
-| Name | 1 to 24 characters: a lowercase letter, then lowercase letters, digits or `_`. Defaults to the folder name (`akms.docs` becomes `akms_docs`). It prefixes the tool names. |
+| Name | 1 to 24 characters: a lowercase letter, then lowercase letters, digits or `_`. Defaults to the folder name (`team.docs` becomes `team_docs`). It prefixes the tool names. |
 | Docs folder | Absolute path of the folder that holds the markdown files. |
-| Exclude | Folder names (`evidence`) or root-relative paths (`ks/archive`) to skip. Folders starting with `.` and `node_modules` are always skipped. |
+| Exclude | Folder names (`evidence`) or root-relative paths (`guide/archive`) to skip. Folders starting with `.` and `node_modules` are always skipped. |
 | Max bytes | Response size limit in UTF-8 bytes. Default 16000, minimum 4000. |
 
 Symbolic links and junctions are not followed. librian only reads your docs; it never writes to them.
@@ -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,20 +95,22 @@ 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 `akms` the tools are `akms__list`, `akms__outline`, `akms__read` and `akms__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 |
 | --- | --- | --- |
-| `list` | `prefix?` | Files with size and document title, grouped by folder. `prefix` is a root-relative path start: `ks/ci` matches `ks/ci/…` and `ks/ci-notes.md`, `ks/ci/` matches the folder only. |
+| `list` | `prefix?` | Files with size and document title, grouped by folder. `prefix` is a root-relative path start: `guide/api` matches `guide/api/…` and `guide/api-notes.md`, `guide/api/` matches the folder only. |
 | `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.
 
@@ -131,7 +133,30 @@ When you pass a reference to another agent or write it into a document, prefer `
 - Words are separated by spaces; wrap a phrase in double quotes to keep it as one word. Matching ignores case.
 - A word made only of letters, digits and `_` matches at the start of a word (`uat` matches `UAT` and `uat_token`, not `evaluate`). Other words, such as Korean, match anywhere.
 - 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 hits, then path and line.
+- 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
 
@@ -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
 
@@ -171,6 +196,8 @@ librian --help | --version
 
 ## Contributing
 
+See [README_DEV.md](README_DEV.md) for the build, the tests and the design.
+
 To run a checkout of this repository instead of the published package, build it (`npm run build`) and install it into the runtime: `npm install --prefix ~/.librian/runtime <path to the checkout>`. The menu then shows the runtime as `linked to <path>`, and **Runtime → Install from npm** switches back.
 
 ## License