@autorag/librarian 2.4.0 → 2.4.2

package/dist/jikji/client.d.ts

@@ -3,6 +3,8 @@ export declare class JikjiClient {
     private readonly options;
     private resolvedCommand;
     constructor(options?: JikjiOptions);
+    /** Jikji stores prepared corpus metadata under a hidden directory in each root. */
+    isPrepared(root: string): boolean;
     /**
      * Resolve the jikji command following the priority chain:
      * 1. explicit binaryPath

package/dist/minsync/client.d.ts

@@ -5,6 +5,7 @@ export interface MinSyncClientOptions {
     readonly embedder?: MinSyncEmbedderConfig;
     readonly maxChunkSize?: number;
 }
+/** MinSync v0.4.2 supports vector, BM25, and hybrid query modes. */
 export type MinSyncQueryMode = "vector" | "bm25" | "hybrid";
 export declare class MinSyncClient {
     private readonly binaryPath;
@@ -12,7 +13,7 @@ export declare class MinSyncClient {
     private readonly embedder;
     private readonly maxChunkSize;
     constructor(options: MinSyncClientOptions);
-    sync(): Promise<MinSyncSyncResult>;
+    sync(force?: boolean): Promise<MinSyncSyncResult>;
     query(text: string, topK: number, mode?: MinSyncQueryMode): Promise<readonly MinSyncQueryHit[]>;
     private spawn;
 }

package/dist/minsync/index.d.ts

@@ -1,7 +1,7 @@
 export { MinSyncClient, type MinSyncClientOptions, type MinSyncQueryMode } from "./client.js";
 export { MINSYNC_CONFIG_DIR, MINSYNC_CONFIG_FILE, minSyncConfigPath, 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 { MinSyncBM25Method, type MinSyncBM25MethodOptions, MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";
+export { MinSyncHybridMethod, type MinSyncHybridMethodOptions, MinSyncVectorMethod, type MinSyncVectorMethodOptions, } from "./method.js";
 export { MINSYNC_FILES_SUBDIR, MINSYNC_SUBDIR, minSyncDocumentPath, minSyncWorkspaceRoot } from "./paths.js";
 export type { MinSyncChunkerConfig, MinSyncEmbedderConfig, MinSyncOptions, MinSyncQueryHit, MinSyncSyncResult, } from "./types.js";
 export { buildMinSyncPathMap, type MinSyncWorkspaceEntry, type MinSyncWorkspaceSyncResult, syncMinSyncWorkspace, } from "./workspace.js";

package/dist/minsync/installer.d.ts

@@ -1,4 +1,5 @@
-export declare const MINSYNC_VERSION = "0.3.0";
+export declare const MINSYNC_VERSION = "0.4.2";
+export declare const MINSYNC_CARGO_INSTALL_TIMEOUT_MS: number;
 export interface MinSyncReleaseAsset {
     readonly name: string;
     readonly downloadUrl: string;
@@ -18,6 +19,11 @@ export interface EnsureMinSyncBinaryOptions {
     readonly arch?: NodeJS.Architecture;
     readonly releaseProvider?: () => Promise<MinSyncRelease>;
     readonly assetInstaller?: (asset: MinSyncReleaseAsset, destination: string) => Promise<void>;
+    /** Test seam: cargo-first installer. Return undefined to fall back to GitHub. */
+    readonly cargoInstaller?: (destination: string) => Promise<InstalledMinSyncBinary | undefined>;
+    /** Test seam: locate cargo on PATH. */
+    readonly cargoLocator?: (env: NodeJS.ProcessEnv) => string | undefined;
+    readonly env?: NodeJS.ProcessEnv;
 }
 export declare function ensureMinSyncBinary(options: EnsureMinSyncBinaryOptions): Promise<InstalledMinSyncBinary>;
 export declare function fetchLatestMinSyncRelease(): Promise<MinSyncRelease>;

package/dist/minsync/method.d.ts

@@ -1,10 +1,10 @@
-import { type BM25Status, type BM25SyncResult } from "../retrieval/methods/bm25.js";
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
 import type { MinSyncQueryMode } from "./client.js";
 import { type EnsureMinSyncBinaryOptions } from "./installer.js";
 import type { MinSyncEmbedderConfig, MinSyncSyncResult } from "./types.js";
 export interface MinSyncVectorMethodOptions {
     readonly root: string;
+    /** Test/embedded override; CLI config intentionally does not persist this. */
     readonly binaryPath?: string;
     readonly workspacePath?: string;
     readonly installer?: Omit<EnsureMinSyncBinaryOptions, "root">;
@@ -13,7 +13,6 @@ export interface MinSyncVectorMethodOptions {
     readonly maxChunkSize?: number;
     readonly mode?: MinSyncQueryMode;
 }
-export type MinSyncBM25MethodOptions = Omit<MinSyncVectorMethodOptions, "mode">;
 export type MinSyncHybridMethodOptions = Omit<MinSyncVectorMethodOptions, "mode">;
 export declare class MinSyncVectorMethod implements RetrievalMethod {
     private readonly root;
@@ -24,34 +23,26 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
     private readonly embedder;
     private readonly maxChunkSize;
     private readonly mode;
+    private installFailed;
     constructor(options: MinSyncVectorMethodOptions);
     describe(): RetrievalMethodDescriptor;
-    sync(): Promise<MinSyncSyncResult>;
-    /** True when a configured binary path is missing (an explicit degraded state). */
+    sync(force?: boolean): Promise<MinSyncSyncResult>;
+    /** Report unavailable binaries without treating auto-install as already failed. */
     isBinaryMissing(): boolean;
+    /** Status distinguishes an explicit missing override from deferred resolution. */
+    isExplicitBinaryMissing(): boolean;
+    /** A vector index is ready only after MinSync has written its cursor. */
+    isReady(): boolean;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
     /**
-     * Resolve the minsync binary path following the priority chain:
-     * 1. explicit binaryPath if set and exists
-     * 2. PATH lookup for `minsync`
-     * 3. cached join(root, '.autorag', 'bin', execName) if exists
-     * 4. if autoInstall===true, try ensureMinSyncBinary in try/catch => install-failed degrade
-     * 5. else return undefined (missing-binary degrade)
+     * Resolve the MinSync CLI from the user's global PATH first, then the
+     * workspace cache, and finally the verified auto-install fallback.
      *
      * Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
      * for install-failed.
      */
     protected resolveBinary(): Promise<string | undefined | MinSyncSyncResult>;
 }
-export declare class MinSyncBM25Method extends MinSyncVectorMethod {
-    private status;
-    constructor(options: MinSyncBM25MethodOptions);
-    describe(): RetrievalMethodDescriptor;
-    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
-    syncFromMinSync(result: MinSyncSyncResult): BM25SyncResult;
-    getStatus(): BM25Status;
-    private resolveBinaryForRetrieve;
-}
 export declare class MinSyncHybridMethod extends MinSyncVectorMethod {
     constructor(options: MinSyncHybridMethodOptions);
     describe(): RetrievalMethodDescriptor;

package/dist/mirror/index.d.ts

@@ -1,5 +1,5 @@
 export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
 export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
-export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath } from "./paths.js";
+export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath } from "./paths.js";
 export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
 export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, syncParsedMirrors } from "./sync.js";

package/dist/mirror/paths.d.ts

@@ -1,6 +1,8 @@
 export declare const PARSED_MIRROR_SUBDIR: string;
 export declare const PARSED_FILES_SUBDIR = "files";
 export declare const PARSED_INDEX_FILE = "index.json";
+export declare const REFRESH_READINESS_FILE = "refresh-complete.json";
 export declare function parsedMirrorRoot(root: string): string;
 export declare function parsedMirrorIndexPath(root: string): string;
 export declare function parsedOutputPath(root: string, virtualPath: string): string;
+export declare function refreshReadinessPath(root: string): string;

package/dist/retrieval/engine.d.ts

@@ -0,0 +1,123 @@
+/**
+ * RetrievalEngine — standalone typed seam for model-free retrieval.
+ *
+ * Wraps the existing retrieval pipeline (registry, parallel retriever,
+ * datasource result filter, and merger) into a single public entry point.
+ * Exposes a deterministic, self-contained retrieval API with diagnostics.
+ *
+ * Security invariants (delegated to {@link DatasourceAccessContext} and
+ * {@link DatasourceResultFilter}):
+ *  - Access is default-deny: when no trusted allow-tags are configured,
+ *    every datasource method result is dropped.
+ *  - Deny is always an explicit empty result array, never `undefined`.
+ *  - Model/tool arguments (`allowedTags`, `allowedScopes`) cannot widen the
+ *    trusted access context constructed during engine creation.
+ */
+import { DatasourceAccessContext, type DatasourceAccessContextOptions } from "../datasource/access-context.js";
+import { RetrievalMethodRegistry } from "./registry.js";
+import type { RetrievalDiagnostic, RetrievalMethod, RetrievalOptions, RetrievalResult } from "./types.js";
+/** Options for constructing a standalone {@link RetrievalEngine}. */
+export interface RetrievalEngineOptions {
+    /**
+     * Datasource access configuration. Default-deny when omitted.
+     * @default { allowedTags: undefined, allowedScopes: undefined }
+     */
+    readonly datasourceAccess?: DatasourceAccessContextOptions;
+    /** Default `topK` when the caller omits it. @default 20 */
+    readonly defaultTopK?: number;
+    /** Default deduplication flag. @default true */
+    readonly defaultDedup?: boolean;
+    /**
+     * Optional predicate that returns `true` when the MinSync binary is missing.
+     * When set, the engine checks every method named `"minsync"`: if the binary
+     * is unavailable the method returns empty results without throwing, the engine
+     * emits a `minsync-unavailable` diagnostic with full method-agnostic path
+     * preservation — matching the existing {@link AutoRAGAgent} behavior.
+     */
+    readonly isMinSyncBinaryMissing?: () => boolean;
+}
+/**
+ * Model-free retrieval pipeline.
+ *
+ * The engine composes the standard AutoRAG retrieval chain:
+ * ```
+ * methods = registry.list()
+ * byMethod = retriever.retrieveWithDiagnostics(methods, query, options)
+ * filtered = filter.filter(byMethod, methods, ctx, options.scope)
+ * merged = merger.merge(filtered, { topK, dedup: true })
+ * → { results: merged, diagnostics }
+ * ```
+ *
+ * Exposes two paths:
+ *  1. `retrieve(query, options?)` — merged results + diagnostics (the standard
+ *     pipeline).
+ *  2. `retrieveByMethod(query, options?)` — per-method results (unmerged) with
+ *     diagnostics, for callers that need the raw per-method view.
+ *
+ * The engine does NOT handle refresh lifecycle, MinSync sync, Jikji, or
+ * agent-level concerns. It is purely the retrieval composition seam.
+ */
+export declare class RetrievalEngine {
+    private readonly registry;
+    private readonly retriever;
+    private readonly filter;
+    private readonly merger;
+    private readonly accessContext;
+    private readonly defaultTopK;
+    private readonly defaultDedup;
+    private readonly isMinSyncBinaryMissing;
+    constructor(options?: RetrievalEngineOptions);
+    /** The underlying method registry. Intentionally public for tooling. */
+    getMethodRegistry(): RetrievalMethodRegistry;
+    /** The underlying datasource access context. Read-only for inspection. */
+    getAccessContext(): DatasourceAccessContext;
+    /**
+     * Register a retrieval method. Overrides the registered-once check from
+     * {@link RetrievalMethodRegistry} per caller requirement.
+     *
+     * @throws {Error} if a method with the same name is already registered.
+     */
+    register(method: RetrievalMethod): void;
+    /**
+     * Register multiple methods in one call. Stop-on-first-error semantics:
+     * registration fails atomically if any method conflicts with an already-
+     * registered name; earlier methods in the batch are not retained.
+     *
+     * @throws {Error} if any method name duplicates an existing or in-batch registration.
+     */
+    registerMany(methods: readonly RetrievalMethod[]): void;
+    /**
+     * Run the full retrieval pipeline — parallel retrieve, datasource filter,
+     * merge — and return merged results with diagnostics.
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<{
+        results: RetrievalResult[];
+        diagnostics: RetrievalDiagnostic[];
+    }>;
+    /**
+     * Run retrieval and return results keyed per method (unmerged) with
+     * diagnostics. Unlike {@link retrieve}, this does NOT merge or sort —
+     * callers get the raw per-method view after datasource filtering.
+     */
+    retrieveByMethod(query: string, options?: RetrievalOptions): Promise<{
+        byMethod: Map<string, RetrievalResult[]>;
+        diagnostics: RetrievalDiagnostic[];
+    }>;
+    /**
+     * Post-check for MinSync binary-missing diagnostic.
+     *
+     * When a registered method named `"minsync"` fails to throw (the method returns
+     * `[]` because the binary is missing), {@link ParallelRetriever} cannot record
+     * a diagnostic. This method checks whether the minsync binary is unavailable
+     * and emits a `minsync-unavailable` diagnostic when every minsync method's
+     * result set is empty, exactly matching the existing {@link AutoRAGAgent}
+     * behavior (see `agent.src/agent/agent.ts` `retrieveWithDiagnostics`).
+     */
+    private appendMinSyncUnavailableDiagnostic;
+    /**
+     * Build a datasource access context scoped to the caller's options.
+     * Model/tool arguments (allowedTags, allowedScopes) from options can only
+     * further restrict the trusted context, never widen it.
+     */
+    private accessContextFor;
+}

package/dist/retrieval/index.d.ts

@@ -1,7 +1,6 @@
+export { RetrievalEngine, type RetrievalEngineOptions } from "./engine.js";
 export type { MergeOptions } from "./merger.js";
 export { ParallelRetriever, ResultMerger } from "./merger.js";
-export type { BM25Engine, BM25ReadinessState, BM25Status, BM25SyncResult } from "./methods/bm25.js";
-export { BM25_SUBDIR, BM25UnavailableError, hasLegacyBm25Artifacts, removeLegacyBm25Artifacts, } from "./methods/bm25.js";
 export { RetrievalMethodRegistry } from "./registry.js";
 export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
 export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalWithDiagnostics, } from "./types.js";

package/dist/retrieval/registry.d.ts

@@ -1,8 +1,8 @@
-import type { RetrievalMethod } from "./types.js";
+import type { RetrievalMethod, RetrievalMethodDescriptor } from "./types.js";
 export declare class RetrievalMethodRegistry {
     private readonly methods;
     register(method: RetrievalMethod): void;
     get(name: string): RetrievalMethod | undefined;
     list(): RetrievalMethod[];
-    getByType(type: "posix" | "vector" | "bm25" | "hybrid" | "visual"): RetrievalMethod[];
+    getByType(type: RetrievalMethodDescriptor["type"]): RetrievalMethod[];
 }

package/dist/retrieval/types.d.ts

@@ -26,7 +26,7 @@ export interface RetrievalMethod {
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
-export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable" | "bm25-unavailable" | "bm25-degraded-fallback";
+export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable";
 /** Path-opaque diagnostic emitted by the multi-method retrieval pipeline. */
 export interface RetrievalDiagnostic {
     code: RetrievalDiagnosticCode;

package/dist/ui/discover.d.ts

@@ -11,8 +11,6 @@ export type DiscoverRun = (binary: string, args: readonly string[]) => Promise<{
     stdout: string;
 }>;
 export declare function listRcloneRemotes(run?: DiscoverRun): Promise<readonly Choice[]>;
-export declare function listMailAccounts(run?: DiscoverRun): Promise<readonly Choice[]>;
-export declare function listHimalayaAccounts(run?: DiscoverRun): Promise<readonly Choice[]>;
 export declare function choicesForType(type: string, run?: DiscoverRun): Promise<{
     rcloneRemotes: readonly Choice[];
     mailAccounts: readonly Choice[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
   "license": "MIT",
   "repository": {
@@ -14,6 +14,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "default": "./dist/core.js"
     }
   },
   "bin": {
@@ -28,7 +32,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/cli/index.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
+    "build": "bun build src/index.ts src/core.ts src/cli/index.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
     "prepublishOnly": "bun run typecheck && bun run build",
     "prepare": "bun run build",
     "test": "node scripts/run-test-files.mjs",

package/skills/autorag/SKILL.md

@@ -11,7 +11,7 @@ summarize, compare, or answer questions from local PDFs, wikis, notes, research
 papers, knowledge bases, or authorized datasources.
 
 AutoRAG is the specialized librarian agent. One configured model plans the
-search, calls BM25, MinSync, Jikji, datasource, and filesystem tools, reads
+search, calls MinSync, Jikji, datasource, and filesystem tools, reads
 sources, judges evidence, and curates the final answer. There is no subagent or
 separate model role.
 
@@ -46,7 +46,7 @@ checks credential presence, and normally probes one live completion. If the
 model, authentication, configuration, or indexes are unhealthy, use
 `autorag-setup` rather than guessing private provider details.
 
-BM25, MinSync, and Jikji should normally be healthy. MinSync and Jikji
+MinSync and Jikji should normally be healthy. MinSync and Jikji
 auto-install on first use by default. If they are missing or stale, run a full
 `autorag refresh` or return to setup rather than silently degrading to
 lexical-only search.
@@ -65,15 +65,28 @@ autorag search "what were the key findings in the Q3 report" --top-k 5 --json --
 `summary`, optional `source`), and `sessionId`. Use that `sessionId` for
 feedback. `--json` without `--debug` is only `answer` plus `results`.
 
+To inspect the exact persisted evidence behind numbered results, use:
+
+```bash
+autorag evidence <sessionId> --result 1 --json
+```
+
+The response includes the original source, retrieval method, stable evidence
+ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber`,
+`retrievalResultId`, and metadata. Omit `--result` to inspect every result in
+the session. Prefer this command whenever the caller wants detailed chunk text
+rather than only the curated summary.
+
 - `--scope` narrows datasource retrieval to a requested sub-path; it cannot
   grant access.
 - `--tags` further narrows already-authorized datasource results and never
   grants new access.
 - `--json` is required for programmatic consumption.
-- `--debug` is required for `sessionId`, evidence, and diagnostics.
+- `--debug` is required for `sessionId` and diagnostics in search output.
+- `autorag evidence` is the detailed source/chunk inspection path.
 
 Do not bypass the librarian with ad hoc raw search when the user requested
-AutoRAG. The search loop can use Jikji, BM25, MinSync, datasource retrieval, and
+AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval, datasource retrieval, and
 direct source reading as appropriate. If search fails because of model,
 provider, auth, or timeout problems, diagnose with `autorag health --json`.
 
@@ -99,9 +112,9 @@ autorag index reset --method bm25 --yes --json
 autorag memory inspect --json
 ```
 
-Prefer a full refresh so parsed mirrors, BM25, MinSync, Jikji, and configured
+Prefer a full refresh so parsed mirrors, MinSync, Jikji, and configured
 datasources stay aligned. `--method` accepts
-`parsed,bm25,minsync,datasources,jikji,all`. Use it only for deliberate
+`parsed,minsync,datasources,jikji,all`. Use it only for deliberate
 narrowing. Scheduled maintenance should use non-daemon `autorag watch --once`,
 typically every 15–30 minutes, with the same config used by search and no
 overlapping runs.

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

@@ -0,0 +1,155 @@
+---
+name: autorag-lite-search
+description: Retrieve documents from an indexed AutoRAG Lite corpus without a model, then persist externally curated reports, inspect evidence, and record numbered feedback. Use when the user wants model-free search, scoped or tag-narrowed retrieval, or the report/evidence/feedback workflow over local documents and authorized datasources.
+license: MIT
+---
+
+# AutoRAG Lite search
+
+Use this skill when AutoRAG Lite is already configured and indexed, and the
+user wants model-free retrieval, or wants to persist an externally curated
+report, inspect its evidence, or record feedback. Use `autorag-lite-setup`
+when config, indexing, or refresh is missing or broken. Use the `autorag`
+skill when a model-backed curated answer is requested.
+
+AutoRAG Lite never mutates sources. Retrieval reads local source documents and
+authorized datasource content; writes go only to workspace `.autorag/` indexes,
+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:
+
+```bash
+autorag lite status --json
+```
+
+`status` is model-free and path-opaque.
+
+## Retrieve
+
+```bash
+autorag lite retrieve "key findings in the Q3 report" --top-k 5 --json
+```
+
+The JSON envelope is:
+
+```json
+{
+  "ok": true,
+  "query": "key findings in the Q3 report",
+  "results": [
+    {
+      "number": 1,
+      "source": "<opaque source identifier>",
+      "method": "minsync",
+      "score": 0.83,
+      "metadata": {},
+      "content": "..."
+    }
+  ],
+  "diagnostics": []
+}
+```
+
+- `--top-k N` must be a positive integer. Invalid values exit with code 2 and
+  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.
+- 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
+  rewrite, guess, or flatten them.
+- `diagnostics` are path-opaque: `source` is a component or method label,
+  never a real filesystem path. Codes include `retrieval-method-failed` and
+  `minsync-unavailable`. A degraded component produces a diagnostic, not a
+  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.
+
+Retrieval methods run in parallel and merge: parsed mirrors and MinSync
+lexical/vector/hybrid methods, plus configured datasource methods. Jikji is a
+local discovery/indexing preparer, not a retrieval method in the lite registry.
+`--method` selection applies to refresh, not retrieve; retrieval always queries
+every active retrieval method.
+
+## Scope and tag narrowing (default-deny)
+
+Datasource access is default-deny from trusted config
+(`datasourceAccess.allowedTags`, `allowedScopes`). Retrieval flags can only
+narrow that access, never widen it:
+
+- `--scope SCOPE` narrows datasource retrieval to a requested sub-path; it
+  cannot grant access to anything the config does not already allow.
+- `--tags tag1,tag2` further narrows already-authorized datasource results by
+  intersecting with configured allowed tags; it never grants new access.
+
+## Persisting a curated report
+
+An external agent curates the raw retrieval results, then persists the
+structured report so evidence and feedback commands work against it:
+
+```bash
+autorag lite report "key findings in the Q3 report" --input report.json --json
+cat report.json | autorag lite report "key findings in the Q3 report" --json
+```
+
+The input is the `emit_autorag_results` JSON schema: `answer`, numbered
+`results` (with `number`, `title`, `summary`, `confidence` in `[0, 1]`,
+optional `source`), and a `mapping` whose entries map each result number to
+its `method` and `source`, plus optional `evidenceRefs` and `warnings`.
+Result and mapping numbers must be one-to-one positive integers. Evidence
+confidence values must be in `[0, 1]`. Invalid input exits with code 2 and
+`{"ok": false, "error": "..."}`.
+
+`source` values in a report are opaque identifiers carried from retrieval
+output. Report persistence performs no filesystem reads against them; it
+stores the identifiers as given. Preserve the exact source-native identities
+from the retrieve envelope.
+
+On success the JSON envelope is:
+
+```json
+{
+  "ok": true,
+  "sessionId": "<uuid>",
+  "query": "key findings in the Q3 report",
+  "answer": "...",
+  "resultCount": 3
+}
+```
+
+Use the returned `sessionId` for evidence inspection and feedback.
+
+## Evidence and feedback
+
+```bash
+autorag evidence <sessionId> --result 1 --json
+autorag feedback <sessionId> --useful 1,3 --not-useful 2 --json
+```
+
+- `evidence` shows the persisted source, retrieval method, stable evidence ID,
+  excerpt or content, and any `chunkIndex`, `lineNumber`, and
+  `retrievalResultId` behind a numbered result. Omit `--result` to inspect the
+  whole session.
+- `feedback` records numbered usefulness so retrieval memory can learn.
+  Numbers refer to the report's result numbers. Supply at least one feedback
+  list.
+- Preserve real source mapping and numbered identifiers end to end: retrieve
+  output feeds the report, the report's session feeds evidence and feedback.
+
+## Rules
+
+- Refresh before retrieval; refresh again when roots change.
+- Use only configured and approved search paths and datasources.
+- Never move, rename, edit, or delete source documents.
+- Never expose provider credentials or authentication payloads.
+- Treat report `source` values as opaque: persist them verbatim, never read
+  the filesystem through them.
+- Keep diagnostics path-opaque; do not reconstruct or disclose real paths
+  from them.
+- Prefer `--json` whenever another agent consumes the output.