@autorag/librarian 2.5.0 → 2.5.1

package/README.md

@@ -323,13 +323,13 @@ Discord uses the external [`discrawl`](https://github.com/openclaw/discrawl) CLI
 brew install openclaw/tap/discrawl
 ```
 
-Two archive sources are supported. `wiretap` (the default) reads the local Discord Desktop cache and needs **no token at all**; `discord` uses a bot token, which is the ToS-sanctioned automation path. AutoRAG refuses to spawn the CLI when a Discord *user* token is present in the environment — automating a user account violates Discord's Community Guidelines and can get the account terminated.
+AutoRAG reads discrawl's own local archive: `discrawl wiretap` imports the Discord Desktop cache and needs **no token at all**, and every search, embed, and sync step runs against that native store. AutoRAG carries no Discord credential — no bot token, no credential env var, no credential check in `autorag setup` — and it refuses to spawn the CLI when a Discord *user* token is present in the environment, because automating a user account violates Discord's Community Guidelines and can get the account terminated. A bot-backed archive is the CLI's own concern: configure and sync it with `discrawl` itself.
 
 ```typescript
 import { AutoRAGAgent, DiscrawlClient, DiscrawlSkill } from "@autorag/librarian";
 
 const discord = new DiscrawlSkill({
-  client: new DiscrawlClient({ source: "wiretap", root: process.cwd() }),
+  client: new DiscrawlClient({ root: process.cwd() }),
   instanceId: "community",
 });
 
@@ -350,7 +350,6 @@ Or through the trusted config factory:
     "discord": {
       "instanceId": "community",
       "connector": {
-        "source": "wiretap",
         "embeddingProvider": "ollama",
         "embeddingModel": "embeddinggemma",
         "defaultMode": "hybrid"
@@ -413,6 +412,8 @@ Config path precedence is `--config` > `AUTORAG_CONFIG` > `~/.autorag/config.jso
 
 `autorag refresh` and `autorag index reset|rebuild` accept `--method <csv>` (e.g. `--method minsync,parsed` or `--method datasources,jikji`) to scope which indexing methods run or which index directories are removed. Valid values are `parsed`, `minsync`, `datasources`, `jikji`, and `all`. BM25 is a MinSync retrieval mode, not a `--method` name. When omitted, all methods run. `autorag init` accepts `--embedder-*` flags to configure the MinSync embedder endpoint in the config file.
 
+`autorag refresh --json` reports the MinSync outcome in a `minsync` block (`ok`, `synced`, and a `reason`/`diagnostics` on failure), and the envelope's `ok` is `false` whenever MinSync, a datasource index, or any error-severity diagnostic failed — a green envelope never hides a semantic index that did not update.
+
 `autorag health` checks model/provider auth before a search — it resolves the model, verifies credential presence, and optionally probes one completion call. Use it to diagnose model, provider, auth, or timeout failures. `autorag status` remains the model-free index-health command (corpus freshness and BM25/MinSync readiness). When `autorag search` fails for a model/provider reason, the error output includes a hint pointing to `autorag health`.
 
 `autorag ui` opens a loopback-only page (`127.0.0.1`) to connect local folders and datasource skills without editing JSON. It writes the same trusted `datasources` / `datasourceAccess` fields as a hand-edited config, stores env-var *names* rather than secrets, and refuses non-loopback binds. Use `--no-open` to print the URL without launching a browser.
@@ -464,7 +465,9 @@ autorag serve                   # P2P peer query server over SimpleX (opt-in)
 autorag p2p                     # peer trust, approvals, and sharing policy
 ```
 
-`autorag --help` is the command list of record. See
+`autorag --help` is the command list of record; `autorag <command> --help`
+prints that command's flags and subcommands, and `autorag --version` prints the
+installed version. See
 [docs/embedding-runtime.md](docs/embedding-runtime.md) for the local embedding
 runtime and gateway setup.
 

package/dist/agent/agent.d.ts

@@ -30,6 +30,9 @@ export interface AutoRAGMinSyncRefreshResult {
     readonly ok: boolean;
     readonly synced: number;
     readonly reason?: string;
+    /** Count of parsed documents excluded from the MinSync index by file name. */
+    readonly stagingExcludedCount?: number;
+    readonly diagnostics?: readonly SearchDocumentDiagnostic[];
 }
 export interface AutoRAGRefreshResult extends Omit<ParsedMirrorSyncResult, "diagnostics"> {
     readonly diagnostics: readonly SearchDocumentDiagnostic[];
@@ -273,6 +276,11 @@ export declare class AutoRAGAgent {
     /**
      * Path-opaque snapshot of corpus freshness and the last refresh outcome. Runs
      * a cheap parse-free staleness scan (stat only); never parses in this path.
+     *
+     * Freshness is read from disk, not from this instance's history: a separate CLI
+     * process (for example `autorag status` or `autorag lite status`) reports the
+     * corpus as current when the last refresh left parsed mirrors behind and no
+     * source has changed since.
      */
     getRefreshStatus(): Promise<AutoRAGRefreshStatus>;
     /**

package/dist/agent/search-documents.d.ts

@@ -10,7 +10,7 @@ export type SearchDocumentDiagnosticSeverity = "info" | "warning" | "error";
  * (#21/#22) does not require another source-breaking type change; codes not yet
  * emitted are still valid members.
  */
-export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "parser-skipped" | "parser-failed" | "pdf-java-version" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "pdf-hybrid-unavailable" | "retrieval-method-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "refresh-failed" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit";
+export type SearchDocumentDiagnosticCode = "empty-query" | "no-verified-results" | "unknown-warning" | "caller-tool-dropped" | "minsync-unavailable" | "minsync-staging-excluded" | "minsync-sync-failed" | "embedder-unavailable" | "embedding-identity-mismatch" | "parser-skipped" | "parser-failed" | "pdf-java-version" | "duplicate-excluded" | "unsupported-file" | "stale-index" | "deleted-mirror" | "pdf-extract-thin" | "pdf-hybrid-unavailable" | "retrieval-method-failed" | "jikji-unavailable" | "jikji-prepare-failed" | "jikji-find-failed" | "refresh-failed" | "watch-failed" | "watch-limited" | "unknown-datasource-skill" | "missing-final-emit";
 export interface SearchDocumentDiagnostic {
     readonly code: SearchDocumentDiagnosticCode;
     readonly severity: SearchDocumentDiagnosticSeverity;

package/dist/cli/command-help.d.ts

@@ -0,0 +1 @@
+export declare function commandUsage(command: string | undefined): string | undefined;

package/dist/cli/commands/lite-retrieve.d.ts

@@ -2,6 +2,11 @@ import type { CommandContext } from "./types.js";
 export interface LiteRetrieveEnvelope {
     readonly ok: true;
     readonly query: string;
+    /**
+     * True when the last refresh does not cover the current sources. Retrieval still
+     * runs; the caller decides whether to trust the result or refresh first.
+     */
+    readonly stale: boolean;
     readonly results: readonly LiteRetrieveResultItem[];
     readonly diagnostics: readonly LiteRetrieveDiagnostic[];
 }
@@ -18,6 +23,10 @@ export interface LiteRetrieveDiagnostic {
     readonly severity: string;
     readonly message: string;
     readonly source?: string;
+    /** Why a source is considered stale, e.g. `mtime-and-size-changed`. */
+    readonly reason?: string;
+    /** Suggested recovery action, e.g. `refresh`. */
+    readonly action?: string;
 }
 /**
  * Run the `autorag lite retrieve` command.

package/dist/cli/index.d.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+declare const COMMANDS: readonly ["init", "setup", "refresh", "status", "search", "feedback", "evidence", "memory", "index", "watch", "health", "duplicates", "tui", "ui", "serve", "p2p", "lite", "models", "gateway"];
+type CommandName = (typeof COMMANDS)[number];
+export type { CommandName };
 interface ParsedArgs {
     positionals: string[];
     flags: Record<string, string | boolean>;
@@ -7,4 +10,3 @@ export declare function parseArgs(argv: readonly string[]): ParsedArgs | {
     error: string;
 };
 export declare function main(argv: readonly string[]): Promise<number>;
-export {};