librian 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [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 "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.
+- **The folder question starts with the current folder.** Start `librian`
+  inside a docs folder and Enter is enough to add it. In your home folder or a
+  drive root the question starts empty.
+
+### Changed
+
+- **Add asks for the folder only.** The Add form with its Name, Exclude and
+  Max bytes rows is gone: the folder is checked (a missing folder is explained
+  and asked again; a folder already added takes you to its entry; a folder
+  without markdown files defaults to No), then one question adds it with the
+  default name. Name, Exclude and Max bytes are changed with **Edit** on the
+  entry, which still opens the form.
+- **Counting files is bounded.** Add, `librian add`, Check and the file counts
+  in the main menu stop at 5,000 files or after 2 seconds and show
+  `5000+ files`, so choosing a huge folder does not hang.
+- **The menu's AI services screen is now called Register.** Its rows and
+  actions are the same: switch Claude Code or Codex on or off, then Apply.
+
+### Removed
+
+- **Runtime → Use a local checkout.** It was for running an unpublished build.
+  Install a built checkout with
+  `npm install --prefix ~/.librian/runtime <path>` instead; the menu still
+  shows it as `linked to <path>` and **Install from npm** switches back.
+
 ## [0.1.0] - 2026-11-08
 
 First release.
@@ -35,5 +81,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

@@ -22,11 +22,11 @@ npx -y librian@latest        # or: npm i -g librian, then run `librian`
 This opens the librian menu. Then:
 
 1. **Runtime → Install**: installs librian into `~/.librian/runtime`.
-2. **Add docs folder**: give it a name and the path of a docs folder (see below). Repeat for more folders.
-3. **AI services**: switch on Claude Code and/or Codex, then **Apply**. librian shows the commands it will run and asks before running them.
+2. **Add docs folder**: type the path of a docs folder. If you started `librian` inside it, the question is already filled in with the current folder, so Enter is enough. Repeat for more folders. Or skip the menu: run `librian add` inside the docs folder (see below).
+3. **Register**: switch on Claude Code and/or Codex, then **Apply**. librian shows the commands it will run and asks before running them.
 4. Open a new session in Claude Code or Codex. Sessions that are already open keep what they started with.
 
-To update, open `librian` → **Runtime → Check for updates**. To undo a registration, switch the service off in **AI services** and **Apply**.
+To update, open `librian` → **Runtime → Check for updates**. To undo a registration, switch the service off in **Register** and **Apply**.
 
 ## The menu
 
@@ -37,20 +37,43 @@ Run `librian` in a terminal. Without a terminal (a pipe or a script) it prints t
 The main screen lists your docs folders; each one is an entry with a name and a path, like a connection in a database tool.
 Choose an entry to **Edit**, **Check** (file count, total size, largest files) or **Remove** it. Removing an entry never touches the folder itself.
 
+**Add docs folder** asks for one thing, the folder, and then adds it:
+
+```
+? Docs folder › D:\workspace\projects\team\team.docs
+  107 markdown files · 4.1M
+? 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 "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.
 
 Adding, editing or removing an entry takes effect in new sessions only.
 
-### AI services
+#### `librian add`
+
+```
+cd path/to/your/docs
+librian add                 # adds the current folder
+librian add path/to/docs    # or a folder you name
+```
+
+The same flow without the menu: it prints the file count, asks `Add it as "…"? (Y/n)` and adds the entry. Without a terminal it reads the answer from a line of input, and if the input ends it adds nothing and exits 0.
+It refuses your home folder and a drive root (exit code 2): run it inside the docs folder or pass the path. A folder that is already added exits 0. When no AI service is registered yet, the last line points you to **Register**.
+
+### Register
 
 Registers librian as one MCP server named `librian` in **Claude Code** and **Codex**, for all your projects (user scope).
 It runs `claude mcp add --scope user …` and `codex mcp add …` for you, and `… mcp remove …` to unregister.
@@ -77,12 +100,12 @@ Set `LIBRIAN_HOME` to use another folder. When it is not the default, the regist
 
 ## 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, 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`.
 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. |
@@ -108,7 +131,7 @@ 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.
 
 ### Limits and continuing
 
@@ -148,7 +171,9 @@ librian --help | --version
 
 ## Contributing
 
-To run a checkout of this repository instead of the published package, build it (`npm run build`) and use **Runtime → Use a local checkout** in the menu.
+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