@autorag/librarian 2.5.0 → 2.5.1

package/dist/minsync/client.d.ts

@@ -14,7 +14,7 @@ export interface MinSyncClientOptions {
     readonly maxChunkSize?: number;
     readonly runtime?: MinSyncRuntime;
 }
-/** MinSync v0.4.2 supports vector, BM25, and hybrid query modes. */
+/** MinSync v0.4.5 supports native vector, BM25, and hybrid query modes. */
 export type MinSyncQueryMode = "vector" | "bm25" | "hybrid";
 export declare class MinSyncQueryError extends Error {
     readonly code: number | null;

package/dist/minsync/embedder-config.d.ts

@@ -9,6 +9,9 @@ export interface MinSyncEmbeddingIdentity {
     readonly runtimeBuild: string;
 }
 export declare const EMBEDDING_IDENTITY_FILE = "autorag-embedding-identity.json";
+export declare const DEFAULT_MINSYNC_EMBEDDER_ID = "native:Qwen/Qwen3-Embedding-0.6B";
+export declare const DEFAULT_MINSYNC_EMBEDDER_DIMENSION = 1024;
+export declare const DEFAULT_MINSYNC_EMBEDDER_CONFIG: MinSyncEmbedderConfig;
 /**
  * MinSync config.toml lives at `<workspace>/.minsync/config.toml`.
  * After `minsync init` runs, we rewrite allowlisted embedder fields so

package/dist/minsync/index.d.ts

@@ -1,5 +1,5 @@
 export { MINSYNC_OLLAMA_MIGRATION_MESSAGE, MinSyncClient, type MinSyncClientOptions, MinSyncQueryError, type MinSyncQueryMode, } from "./client.js";
-export { configuredVectorDimension, MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, type MinSyncEmbeddingIdentity, minSyncConfigPath, minSyncEmbeddingIdentityPath, rewriteEmbedderConfig, } from "./embedder-config.js";
+export { configuredVectorDimension, DEFAULT_MINSYNC_EMBEDDER_CONFIG, DEFAULT_MINSYNC_EMBEDDER_DIMENSION, DEFAULT_MINSYNC_EMBEDDER_ID, MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, type MinSyncEmbeddingIdentity, minSyncConfigPath, minSyncEmbeddingIdentityPath, rewriteEmbedderConfig, } from "./embedder-config.js";
 export { type EnsureMinSyncBinaryOptions, ensureMinSyncBinary, executableName, fetchLatestMinSyncRelease, type InstalledMinSyncBinary, MINSYNC_VERSION, type MinSyncRelease, type MinSyncReleaseAsset, MinSyncReleaseError, selectReleaseAsset, } from "./installer.js";
 export { ensureLocalEmbedder, LocalEmbedderError, type LocalEmbedderPreflightOptions, } from "./local-embedder.js";
 export { MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";

package/dist/minsync/installer.d.ts

@@ -1,4 +1,4 @@
-export declare const MINSYNC_VERSION = "0.4.2";
+export declare const MINSYNC_VERSION = "0.4.5";
 export declare const MINSYNC_CARGO_INSTALL_TIMEOUT_MS: number;
 export interface MinSyncReleaseAsset {
     readonly name: string;

package/dist/minsync/method.d.ts

@@ -30,6 +30,7 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
     constructor(options: MinSyncVectorMethodOptions);
     describe(): RetrievalMethodDescriptor;
     sync(force?: boolean): Promise<MinSyncSyncResult>;
+    private syncUnlocked;
     /** Report unavailable binaries without treating auto-install as already failed. */
     isBinaryMissing(): boolean;
     /** Status distinguishes an explicit missing override from deferred resolution. */
@@ -37,6 +38,7 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
     /** A vector index is ready only after MinSync has written its cursor. */
     isReady(): boolean;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    private retrieveUnlocked;
     /**
      * Resolve the MinSync CLI from the user's global PATH first, then the
      * workspace cache, and finally the verified auto-install fallback.

package/dist/minsync/types.d.ts

@@ -33,8 +33,14 @@ export interface MinSyncSyncResult {
     readonly workspacePath: string;
     readonly reason?: string;
     readonly diagnostic?: MinSyncDiagnostic;
+    /**
+     * Parsed-mirror ids that could not be staged for indexing because the file
+     * name has no canonical source-id form. Surfaced as diagnostics so an
+     * unindexable document is never dropped silently.
+     */
+    readonly stagingExcluded?: readonly string[];
 }
-export type MinSyncDiagnosticCode = "embedder-unavailable" | "no-hit" | "embedding-identity-mismatch" | "migration-required";
+export type MinSyncDiagnosticCode = "embedder-unavailable" | "sync-failed" | "no-hit" | "embedding-identity-mismatch" | "migration-required";
 export interface MinSyncDiagnostic {
     readonly code: MinSyncDiagnosticCode;
     readonly message: string;

package/dist/minsync/workspace.d.ts

@@ -7,6 +7,12 @@ export interface MinSyncWorkspaceEntry {
 export interface MinSyncWorkspaceSyncResult {
     readonly workspacePath: string;
     readonly entries: readonly MinSyncWorkspaceEntry[];
+    /**
+     * Parsed-mirror ids that could not be staged: no canonical source-id form
+     * or a missing parsed output. Callers report these instead of dropping
+     * them silently.
+     */
+    readonly excluded: readonly string[];
 }
 export declare function syncMinSyncWorkspace(root: string, options?: {
     readonly workspacePath?: string;

package/dist/mirror/index-store.d.ts

@@ -7,9 +7,26 @@ export interface ParsedMirrorEntry {
     readonly sourceSizeBytes: number;
     readonly updatedAt: string;
 }
+/** Why refresh deliberately left a source out of the parsed mirror. */
+export type ParsedMirrorSkipReason = "duplicate-excluded" | "parser-skipped" | "parser-failed";
+/**
+ * A source the last refresh decided not to mirror, pinned to the exact version it
+ * decided on. Staleness checks compare against this record instead of re-deriving
+ * the decision, so a deliberately skipped file is not reported as a new source.
+ */
+export interface ParsedMirrorSkipEntry {
+    readonly virtualPath: string;
+    readonly sourcePath: string;
+    readonly reason: ParsedMirrorSkipReason;
+    readonly sourceMtimeNs: number;
+    readonly sourceSizeBytes: number;
+    readonly updatedAt: string;
+}
 export interface ParsedMirrorIndex {
     readonly version: 1;
     readonly entries: Readonly<Record<string, ParsedMirrorEntry>>;
+    /** Deliberate skips recorded by the last refresh. Absent in indexes written before this field existed. */
+    readonly skipped?: Readonly<Record<string, ParsedMirrorSkipEntry>>;
 }
 export declare function emptyMirrorIndex(): ParsedMirrorIndex;
 export declare function loadMirrorIndex(root: string): ParsedMirrorIndex;

package/dist/mirror/sync.d.ts

@@ -33,9 +33,12 @@ export interface ParsedMirrorSyncResult {
 export declare function syncParsedMirrors(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorSyncResult>;
 /**
  * Cheap, parse-free staleness check: compares current source files (by mtime and
- * size only — no parsing) against the recorded mirror index. Returns a
- * `stale-index` diagnostic (opaque virtual path) for every supported source that
- * is new or changed since the last successful refresh. Safe to call outside the
- * query hot path (e.g. from getRefreshStatus).
+ * size only — no parsing) against the mirror index's own records. A source is
+ * current when the last refresh either indexed it or deliberately skipped it at
+ * this exact version, so a skipped duplicate, oversize, or unparseable file is not
+ * reported as a new source. Returns a `stale-index` diagnostic (opaque virtual
+ * path) for every supported source that is new or changed since the last
+ * successful refresh. Safe to call outside the query hot path (e.g. from
+ * getRefreshStatus).
  */
 export declare function detectMirrorStaleness(options: ParsedMirrorSyncOptions): Promise<ParsedMirrorDiagnostic[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
   "license": "MIT",
   "repository": {
@@ -68,7 +68,7 @@
     "yaml": "^2.9.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.12",
+    "@biomejs/biome": "2.5.13",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^26.4.1",
     "@types/ws": "^8.18.1",

package/skills/autorag/SKILL.md

@@ -139,5 +139,7 @@ Never target source documents. `memory inspect` is read-only and path-opaque.
   call `autorag feedback`.
 - Do not invent CLI commands. `autorag --help` is the command list of record,
   including the shipped `gateway`, `models`, `serve`, `p2p`, `tui`, and `lite`
-  commands. See `docs/embedding-runtime.md` for the local embedding runtime
+  commands. `autorag <command> --help` prints that command's own flags, and
+  `autorag --version` prints the installed version. See
+  `docs/embedding-runtime.md` for the local embedding runtime
   and gateway setup.

package/skills/autorag-lite-search/SKILL.md

@@ -18,15 +18,22 @@ the memory file, and Jikji `.jikji/` caches.
 
 ## Preflight
 
-Retrieval requires a completed refresh. If `autorag lite retrieve` returns
-exit code 2 with an `index-not-ready` diagnostic, run `autorag lite refresh`
-(or `autorag refresh`) first, then retry. Confirm freshness with:
+Retrieval needs a completed refresh. If `autorag lite retrieve` returns exit
+code 2 with an `index-not-ready` diagnostic, no refresh has completed yet —
+run `autorag lite refresh` (or `autorag refresh`) first, then retry. Confirm
+freshness with:
 
 ```bash
 autorag lite status --json
 ```
 
-`status` is model-free and path-opaque.
+`status` is model-free and path-opaque, and its `stale` field is read from disk,
+so it answers "is indexing complete?" even from a fresh process.
+
+A stale corpus is not a failure: `retrieve` answers from the index it has and
+reports the staleness it is answering past (`"stale": true` plus `stale-index`
+diagnostics). Pass `--refresh` to rebuild incrementally before answering, or
+`--strict` to keep the old fail-closed behavior and exit 2 instead of answering.
 
 ## Retrieve
 
@@ -40,6 +47,7 @@ The JSON envelope is:
 {
   "ok": true,
   "query": "key findings in the Q3 report",
+  "stale": false,
   "results": [
     {
       "number": 1,
@@ -58,6 +66,15 @@ The JSON envelope is:
   an `{"ok": false, "error": "..."}` rejection envelope.
 - Before any refresh, the envelope is `{"ok": false, "query": ..., "diagnostics":
   [{"code": "index-not-ready", "severity": "error", ...}]}` with exit code 2.
+- `stale: true` means the last refresh does not cover the current sources; the
+  results are still returned. Each entry in `diagnostics` with code
+  `stale-index` names the opaque source and a `reason` (for example
+  `mtime-and-size-changed`) plus `action: "refresh"`. Sources the refresh
+  deliberately skipped (exact duplicates, oversized or unparseable files, and
+  AutoRAG/Jikji product artifacts) are not stale.
+- `--refresh` runs an incremental refresh before answering and reports the
+  corpus current; `--strict` exits 2 with the `index-not-ready` envelope when the
+  index is stale, for callers that must not answer from a stale index.
 - Each result carries a provenance pair: the `source` identity and the
   `method` that produced it. Source identities are source-native: real file
   paths for local files, datasource identities for datasource results. Never
@@ -68,8 +85,9 @@ The JSON envelope is:
   failed run; check `diagnostics` before trusting an empty result set.
 - `--debug` adds diagnostic detail to human output without printing real
   filesystem paths.
-- Exit codes: 0 on success (results may be empty), 2 for usage, config, or
-  not-ready errors, 1 for runtime errors.
+- Exit codes: 0 on success (results may be empty, and a stale index is a
+  warning rather than a failure), 2 for usage, config, not-ready, or
+  `--strict` staleness errors, 1 for runtime errors.
 
 Retrieval methods run in parallel and merge: parsed mirrors and MinSync
 lexical/vector/hybrid methods, plus configured datasource methods. Jikji is a

package/skills/autorag-lite-setup/SKILL.md

@@ -128,6 +128,14 @@ Retrieval requires a completed refresh. `autorag lite retrieve` before any
 refresh exits with code 2 and an `index-not-ready` diagnostic; a successful
 refresh is recorded even when the corpus is empty or only a non-parsed method
 was selected. Always refresh first, and refresh again when roots change.
+Once a refresh has completed, staleness is reported rather than enforced: a
+source that changed afterwards gives `"stale": true` with `stale-index`
+diagnostics (and `autorag lite status` reports `stale: true`) while retrieval
+still answers from the index. Sources the refresh deliberately skipped — exact
+duplicates, oversized or unparseable files, and AutoRAG/Jikji product artifacts
+such as `.jikji_agent_map.md` — do not count as stale. Use `autorag lite
+retrieve --refresh` to rebuild incrementally before one query, or `--strict`
+when a stale index must fail instead of answering.
 Jikji is a discovery/indexing preparer, not a lite retrieval method.
 
 ## Watch and scheduled freshness