librian 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -4,13 +4,24 @@ 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 "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 +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

@@ -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.
@@ -100,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. |
@@ -131,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
 
@@ -171,6 +171,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

package/dist/cli.js

@@ -7263,7 +7263,7 @@ import { resolve as resolve5 } from "node:path";
 // package.json
 var package_default = {
   name: "librian",
-  version: "0.1.1",
+  version: "0.1.2",
   description: "Find and read sections of a markdown docs folder over MCP, with outlines and line ranges that stay current as the docs change",
   repository: {
     type: "git",
@@ -9435,7 +9435,7 @@ var USAGE = [
   "",
   "  --catalog          Read the docs folders from <LIBRIAN_HOME>/catalog.json (default ~/.librian)",
   "  --root <folder>    Markdown docs folder to serve",
-  "  --exclude <name>   Skip a folder name (e.g. evidence) or a root-relative path (e.g. ks/archive); repeatable",
+  "  --exclude <name>   Skip a folder name (e.g. evidence) or a root-relative path (e.g. guide/archive); repeatable",
   `  --max-bytes <n>    Response size limit in UTF-8 bytes (default ${DEFAULT_MAX_BYTES}, minimum ${MIN_MAX_BYTES})`,
   "  --help             Show this help",
   "  --version          Show the version"
@@ -39044,7 +39044,7 @@ function normalizePrefix(prefix) {
 }
 function runList(library, args, maxBytes) {
   if (args.prefix != null && typeof args.prefix != "string") {
-    return errorResult('prefix must be a string: the start of a path such as "ks/ci".');
+    return errorResult('prefix must be a string: the start of a path such as "guide/api".');
   }
   let prefix = "";
   if (typeof args.prefix == "string") {
@@ -39508,6 +39508,8 @@ var ELLIPSIS2 = "\u2026";
 var ELLIPSIS_BYTES = Buffer.byteLength(ELLIPSIS2);
 var QUERY_ECHO_MAX_CHARS = 80;
 var WORD_CHARACTERS = /[a-z0-9_]/;
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
 function normalize(text2) {
   return text2.normalize("NFC").toLowerCase();
 }
@@ -39605,14 +39607,18 @@ function matchBlock(document, start, end, chainText, label, bodyStart, terms) {
     }
     hits += counts[termIndex];
   }
-  return { document, start, end, label, bytes: document.bytesOf(start, end), hits, titleHits, bodyStart };
+  return { document, start, end, label, bytes: document.bytesOf(start, end), termCounts: counts, hits, titleHits, score: 0, bodyStart };
 }
 function collectMatches(documents, terms) {
   const matches = [];
+  let scannedBytes = 0;
+  let scannedBlocks = 0;
   for (const document of documents) {
     const headings = document.headings;
     const introEnd = headings.length == 0 ? document.lines.length : headings[0].line - 1;
     if (introEnd >= 1 && isBlank(document, 1, introEnd) == false) {
+      scannedBytes += document.bytesOf(1, introEnd);
+      scannedBlocks += 1;
       const introMatch = matchBlock(document, 1, introEnd, "", INTRO_TITLE, 1, terms);
       if (introMatch != null) {
         matches.push(introMatch);
@@ -39620,6 +39626,8 @@ function collectMatches(documents, terms) {
     }
     for (let index = 0; index < headings.length; index += 1) {
       const heading = headings[index];
+      scannedBytes += document.bytesOf(heading.line, heading.blockEnd);
+      scannedBlocks += 1;
       const chainText = chainIndices(document, index).map((position) => document.headings[position].title).join("\n");
       const label = headingChain(document, index);
       const match = matchBlock(document, heading.line, heading.blockEnd, chainText, label, heading.line + 1, terms);
@@ -39628,14 +39636,22 @@ function collectMatches(documents, terms) {
       }
     }
   }
-  return matches;
+  return { matches, averageBytes: scannedBlocks == 0 ? 1 : scannedBytes / scannedBlocks };
+}
+function scoreMatch(match, averageBytes) {
+  const lengthFactor = 1 - BM25_B + BM25_B * (match.bytes / averageBytes);
+  let score = 0;
+  for (const termCount of match.termCounts) {
+    score += termCount * (BM25_K1 + 1) / (termCount + BM25_K1 * lengthFactor);
+  }
+  return score;
 }
 function compareMatches(left, right) {
   if (left.titleHits != right.titleHits) {
     return right.titleHits - left.titleHits;
   }
-  if (left.hits != right.hits) {
-    return right.hits - left.hits;
+  if (left.score != right.score) {
+    return right.score - left.score;
   }
   const byPath = compareText(left.document.path, right.document.path);
   if (byPath != 0) {
@@ -39725,7 +39741,10 @@ function runSearch(library, args, maxBytes) {
     return errorResult("Query is empty. Give one or more words; wrap a phrase in double quotes.");
   }
   const documents = library.refresh().filter((document) => document.path.startsWith(prefix));
-  const matches = collectMatches(documents, terms);
+  const { matches, averageBytes } = collectMatches(documents, terms);
+  for (const match of matches) {
+    match.score = scoreMatch(match, averageBytes);
+  }
   matches.sort(compareMatches);
   const fileCount = new Set(matches.map((match) => match.document.path)).size;
   const echo = JSON.stringify(truncateChars(query.trim(), QUERY_ECHO_MAX_CHARS));
@@ -39801,9 +39820,9 @@ function describeTools(folder) {
   return [
     {
       name: nameOf("list"),
-      description: `${tag}List the markdown files under ${where} with size and document title, grouped by folder. Use prefix to open one folder: \`ks/ci\` matches \`ks/ci/\u2026\` and \`ks/ci-web-renewal.md\`, \`ks/ci/\` matches the folder only.`,
+      description: `${tag}List the markdown files under ${where} with size and document title, grouped by folder. Use prefix to open one folder: \`guide/api\` matches \`guide/api/\u2026\` and \`guide/api-notes.md\`, \`guide/api/\` matches the folder only.`,
       inputSchema: {
-        prefix: external_exports.string().optional().describe("Root-relative path prefix, e.g. `ks/ci/`. Omit to list everything.")
+        prefix: external_exports.string().optional().describe("Root-relative path prefix, e.g. `guide/api/`. Omit to list everything.")
       },
       runner: runList
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "librian",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Find and read sections of a markdown docs folder over MCP, with outlines and line ranges that stay current as the docs change",
   "repository": {
     "type": "git",