@autorag/librarian 2.6.3 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/NOTICE +6 -0
  2. package/README.md +76 -25
  3. package/dist/agent/agent.d.ts +135 -27
  4. package/dist/agent/answer-guidelines.d.ts +19 -0
  5. package/dist/agent/citations.d.ts +20 -0
  6. package/dist/agent/index.d.ts +1 -0
  7. package/dist/agent/jev-extension.d.ts +68 -0
  8. package/dist/agent/pi-session.d.ts +55 -0
  9. package/dist/agent/query-decomposition.d.ts +25 -0
  10. package/dist/agent/query-routing.d.ts +54 -0
  11. package/dist/agent/search-documents.d.ts +2 -2
  12. package/dist/agent/system-prompt.d.ts +1 -0
  13. package/dist/cli/commands/evidence.d.ts +22 -0
  14. package/dist/cli/commands/health.d.ts +2 -3
  15. package/dist/cli/commands/init.d.ts +2 -1
  16. package/dist/cli/commands/models.d.ts +20 -0
  17. package/dist/cli/commands/search.d.ts +2 -2
  18. package/dist/cli/commands/serve.d.ts +2 -2
  19. package/dist/cli/commands/tui.d.ts +12 -35
  20. package/dist/cli/commands/update-check.d.ts +8 -0
  21. package/dist/cli/config.d.ts +82 -5
  22. package/dist/cli/index.d.ts +1 -1
  23. package/dist/cli/index.js +9802 -9324
  24. package/dist/cli/update-check.d.ts +34 -0
  25. package/dist/cli/version.d.ts +5 -0
  26. package/dist/core.d.ts +34 -2
  27. package/dist/core.js +9848 -8977
  28. package/dist/everything/bundle.d.ts +15 -3
  29. package/dist/everything/client.d.ts +22 -5
  30. package/dist/everything/index.d.ts +1 -1
  31. package/dist/filesystem/name-search.d.ts +57 -0
  32. package/dist/fsearch/client.d.ts +7 -1
  33. package/dist/index.d.ts +1 -0
  34. package/dist/index.js +11181 -9015
  35. package/dist/jikji/client.d.ts +6 -1
  36. package/dist/mcp/index.d.ts +2 -0
  37. package/dist/mcp/index.js +29949 -0
  38. package/dist/mcp/server.d.ts +9 -0
  39. package/dist/minsync/method.d.ts +6 -3
  40. package/dist/mirror/index.d.ts +1 -1
  41. package/dist/mirror/paths.d.ts +6 -0
  42. package/dist/retrieval/engine.d.ts +32 -1
  43. package/dist/retrieval/index.d.ts +2 -1
  44. package/dist/retrieval/rerank.d.ts +8 -3
  45. package/dist/retrieval/selection.d.ts +97 -0
  46. package/package.json +10 -3
  47. package/skills/autorag/SKILL.md +25 -4
  48. package/skills/autorag-doctor/SKILL.md +27 -18
  49. package/skills/autorag-lite-setup/SKILL.md +115 -59
  50. package/skills/autorag-setup/SKILL.md +99 -16
  51. package/dist/agent/bash-tool.d.ts +0 -32
  52. package/dist/cli/tui-commands.d.ts +0 -16
  53. package/dist/cli/tui-session-store.d.ts +0 -16
  54. package/skills/autorag-lite-search/SKILL.md +0 -245
@@ -0,0 +1,9 @@
1
+ import { McpServer } from "@modelcontextprotocol/server";
2
+ import type { AutoRAGLite } from "../core.js";
3
+ export interface AutoRAGMcpServerOptions {
4
+ readonly readOnly?: boolean;
5
+ readonly tools?: readonly string[];
6
+ /** Test/embedded override; defaults to the current Node platform. */
7
+ readonly platform?: NodeJS.Platform;
8
+ }
9
+ export declare function createAutoRAGMcpServer(lite: AutoRAGLite, options?: AutoRAGMcpServerOptions): McpServer;
@@ -32,7 +32,6 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
32
32
  private readonly runtime;
33
33
  private readonly defaultTopK;
34
34
  private readonly scopedTopK;
35
- private installFailed;
36
35
  constructor(options: MinSyncVectorMethodOptions);
37
36
  describe(): RetrievalMethodDescriptor;
38
37
  sync(force?: boolean): Promise<MinSyncSyncResult>;
@@ -47,12 +46,16 @@ export declare class MinSyncVectorMethod implements RetrievalMethod {
47
46
  private retrieveUnlocked;
48
47
  /**
49
48
  * Resolve the MinSync CLI from the user's global PATH first, then the
50
- * workspace cache, and finally the verified auto-install fallback.
49
+ * workspace cache, and finally the verified auto-install fallback. The
50
+ * auto-install runs only for `sync` (refresh); queries pass
51
+ * `install: false` so a user's turn never waits on `cargo install`.
51
52
  *
52
53
  * Returns: string path on success, undefined for missing-binary, or a MinSyncSyncResult
53
54
  * for install-failed.
54
55
  */
55
- protected resolveBinary(): Promise<string | undefined | MinSyncSyncResult>;
56
+ protected resolveBinary(options?: {
57
+ readonly install?: boolean;
58
+ }): Promise<string | undefined | MinSyncSyncResult>;
56
59
  }
57
60
  export declare class MinSyncHybridMethod extends MinSyncVectorMethod {
58
61
  constructor(options: MinSyncHybridMethodOptions);
@@ -1,5 +1,5 @@
1
1
  export type { ParsedMirrorEntry, ParsedMirrorIndex } from "./index-store.js";
2
2
  export { emptyMirrorIndex, loadMirrorIndex, saveMirrorIndex } from "./index-store.js";
3
- export { parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath } from "./paths.js";
3
+ export { isParsedRefreshComplete, parsedMirrorIndexPath, parsedMirrorRoot, parsedOutputPath, refreshReadinessPath, } from "./paths.js";
4
4
  export type { ParsedMirrorDiagnostic, ParsedMirrorDiagnosticCode, ParsedMirrorSyncOptions, ParsedMirrorSyncResult, } from "./sync.js";
5
5
  export { DEFAULT_MAX_SOURCE_BYTES, detectMirrorStaleness, isPathExcluded, syncParsedMirrors } from "./sync.js";
@@ -8,3 +8,9 @@ export declare function parsedMirrorIndexPath(root: string): string;
8
8
  export declare function parsedOutputPath(root: string, virtualPath: string): string;
9
9
  export declare function refreshReadinessPath(root: string): string;
10
10
  export declare function refreshProgressPath(root: string): string;
11
+ /**
12
+ * Whether a parsed-mirror refresh has completed at least once for the given
13
+ * workspace. Reads the persisted readiness marker so a separate process (CLI,
14
+ * MCP server) reaches the same verdict as the process that ran the refresh.
15
+ */
16
+ export declare function isParsedRefreshComplete(workspacePath: string): boolean;
@@ -15,7 +15,8 @@
15
15
  */
16
16
  import { DatasourceAccessContext, type DatasourceAccessContextOptions } from "../datasource/access-context.js";
17
17
  import { RetrievalMethodRegistry } from "./registry.js";
18
- import type { Reranker } from "./rerank.js";
18
+ import { type Reranker } from "./rerank.js";
19
+ import { type RetrievalSelection } from "./selection.js";
19
20
  import type { RetrievalDiagnostic, RetrievalMethod, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } from "./types.js";
20
21
  /** Options for constructing a standalone {@link RetrievalEngine}. */
21
22
  export interface RetrievalEngineOptions {
@@ -41,6 +42,14 @@ export interface RetrievalEngineOptions {
41
42
  * preservation — matching the existing {@link AutoRAGAgent} behavior.
42
43
  */
43
44
  readonly isMinSyncBinaryMissing?: () => boolean;
45
+ /**
46
+ * Authorized datasource ids from the skill catalog, including datasources
47
+ * that expose no retrieval methods. {@link retrieveSelected} uses this to
48
+ * tell an unknown datasource id from an unauthorized one. When omitted, the
49
+ * engine derives ids from its authorized registered methods; method-less
50
+ * datasources are then treated as unknown.
51
+ */
52
+ readonly authorizedDatasourceIds?: () => readonly string[];
44
53
  /**
45
54
  * Optional post-merge reranker. When set, merged results are reordered by
46
55
  * the reranker after dedup and score normalization. A reranker failure is
@@ -48,6 +57,11 @@ export interface RetrievalEngineOptions {
48
57
  * the engine never silently drops evidence because a reranker was down.
49
58
  */
50
59
  readonly reranker?: Reranker;
60
+ /**
61
+ * Number of merged results kept after reranking when the caller omits `topK`.
62
+ * Only applies when {@link reranker} is set. @default DEFAULT_RERANK_TOP_N
63
+ */
64
+ readonly rerankTopN?: number;
51
65
  }
52
66
  /**
53
67
  * Model-free retrieval pipeline.
@@ -79,7 +93,9 @@ export declare class RetrievalEngine {
79
93
  private readonly defaultTopK;
80
94
  private readonly defaultDedup;
81
95
  private readonly isMinSyncBinaryMissing;
96
+ private readonly authorizedDatasourceIdsProvider;
82
97
  private readonly reranker;
98
+ private readonly rerankTopN;
83
99
  constructor(options?: RetrievalEngineOptions);
84
100
  /** The underlying method registry. Intentionally public for tooling. */
85
101
  getMethodRegistry(): RetrievalMethodRegistry;
@@ -124,6 +140,21 @@ export declare class RetrievalEngine {
124
140
  diagnostics: RetrievalDiagnostic[];
125
141
  unsearched: RetrievalUnsearchedSurface[];
126
142
  }>;
143
+ /**
144
+ * Run a selected subset of the registered methods — parallel retrieve,
145
+ * datasource filter, merge — and return merged results with diagnostics.
146
+ *
147
+ * Unlike {@link retrieve}, selection happens BEFORE any backend is invoked:
148
+ * the eligible method list is reduced first, so an unselected or
149
+ * unauthorized datasource backend is never spawned. Unknown or unauthorized
150
+ * method/datasource selections throw {@link RetrievalSelectionError}. The
151
+ * trusted access context still narrows results/tags/scopes after retrieval.
152
+ */
153
+ retrieveSelected(query: string, selection?: RetrievalSelection, options?: RetrievalOptions): Promise<{
154
+ results: RetrievalResult[];
155
+ diagnostics: RetrievalDiagnostic[];
156
+ unsearched: RetrievalUnsearchedSurface[];
157
+ }>;
127
158
  /**
128
159
  * Post-check for MinSync binary-missing diagnostic.
129
160
  *
@@ -2,7 +2,8 @@ export { RetrievalEngine, type RetrievalEngineOptions } from "./engine.js";
2
2
  export type { MergeOptions } from "./merger.js";
3
3
  export { ParallelRetriever, ResultMerger } from "./merger.js";
4
4
  export { RetrievalMethodRegistry } from "./registry.js";
5
- export { type CreateRerankerOptions, createReranker, DEFAULT_RERANK_API_KEY_ENV, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_PROVIDER, OpenRouterReranker, type OpenRouterRerankerOptions, type Reranker, type RerankerDescriptor, type RerankOptions, } from "./rerank.js";
5
+ export { type CreateRerankerOptions, createReranker, DEFAULT_RERANK_API_KEY_ENV, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_PROVIDER, DEFAULT_RERANK_TOP_N, OpenRouterReranker, type OpenRouterRerankerOptions, type Reranker, type RerankerDescriptor, type RerankOptions, SUPPORTED_RERANK_PROVIDERS, } from "./rerank.js";
6
6
  export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
7
+ export { type DatasourceCatalogEntry, derivedAuthorizedDatasourceIds, type RetrievalSelection, RetrievalSelectionError, type RetrievalSelectionErrorCode, resolveSelectedMethods, } from "./selection.js";
7
8
  export { describeRetrievalError, groupUnsearchedSurfaces, MINSYNC_SURFACE, type RetrievalSkip, retrievalSurfaceFor, } from "./skip.js";
8
9
  export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface, RetrievalWithDiagnostics, } from "./types.js";
@@ -18,6 +18,10 @@ export declare const DEFAULT_RERANK_MODEL = "voyageai/rerank-3-lite";
18
18
  export declare const DEFAULT_RERANK_PROVIDER = "openrouter";
19
19
  /** Default environment variable holding the OpenRouter API key. */
20
20
  export declare const DEFAULT_RERANK_API_KEY_ENV = "OPENROUTER_API_KEY";
21
+ /** Default number of merged chunks kept after reranking. */
22
+ export declare const DEFAULT_RERANK_TOP_N = 25;
23
+ /** Rerank providers {@link createReranker} can build. */
24
+ export declare const SUPPORTED_RERANK_PROVIDERS: readonly string[];
21
25
  /** Static description of a reranker, used for diagnostics and inspection. */
22
26
  export interface RerankerDescriptor {
23
27
  /** Stable label (e.g. `openrouter`). */
@@ -57,6 +61,8 @@ export interface RerankClient {
57
61
  documents: string[];
58
62
  topN?: number;
59
63
  };
64
+ }, options?: {
65
+ signal?: AbortSignal;
60
66
  }): Promise<RerankResponse>;
61
67
  }
62
68
  /** Response body returned by OpenRouter's rerank router. */
@@ -92,9 +98,8 @@ export interface CreateRerankerOptions extends OpenRouterRerankerOptions {
92
98
  }
93
99
  /**
94
100
  * Build the configured reranker. Returns `undefined` when reranking is disabled
95
- * or absent, or when the provider is unsupported. Provider-agnostic by design:
96
- * a local reranker implements {@link Reranker} and plugs in here without
97
- * touching the retrieval pipeline.
101
+ * or absent. Throws for a provider AutoRAG cannot build (an unsupported
102
+ * `provider` id is a configuration error, not a silent no-op).
98
103
  */
99
104
  export declare function createReranker(config: CreateRerankerOptions | false | undefined): Reranker | undefined;
100
105
  /**
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Selection gating for the retrieval pipeline.
3
+ *
4
+ * `searchSelected` lets a caller narrow a search to specific datasources,
5
+ * specific methods, or the local (non-datasource) surfaces *before* any backend
6
+ * is invoked. This module owns that narrowing so the engine can reuse its
7
+ * existing parallel-retrieve / datasource-filter / merge chain on the reduced
8
+ * method list instead of fanning out to every backend and filtering afterwards.
9
+ *
10
+ * Security invariants:
11
+ * - Unauthorized datasource methods are never selected, whether or not the
12
+ * caller passed a selection — an unselected search still excludes them, so
13
+ * no denied backend is executed.
14
+ * - A caller-supplied selection can only *narrow* the trusted method set; it
15
+ * can never widen it. Unknown or unauthorized method/datasource names are
16
+ * rejected with a typed error, never silently resolved.
17
+ * - The trusted {@link DatasourceAccessContext} remains the sole authority:
18
+ * the `authorizedDatasourceIds` catalog is itself built from that context.
19
+ */
20
+ import type { DatasourceAccessContext } from "../datasource/access-context.js";
21
+ import type { RetrievalMethod } from "./types.js";
22
+ /**
23
+ * Model-free, credential-free descriptor of one authorized configured
24
+ * datasource, for catalog/listing surfaces. Carries no credentials, config
25
+ * paths, or raw instance metadata — only the identity, capability tags, and
26
+ * the opaque source scope strings the access context authorizes.
27
+ */
28
+ export interface DatasourceCatalogEntry {
29
+ /** Stable datasource id, e.g. `"kakao"`. */
30
+ readonly datasourceId: string;
31
+ /** Skill name, e.g. `"kakao"`. */
32
+ readonly name: string;
33
+ /** Skill kind, e.g. `"chat"` or `"chat-export"`. */
34
+ readonly type: string;
35
+ /** Human-readable description. */
36
+ readonly description: string;
37
+ /** Authorization tags that made this datasource accessible. */
38
+ readonly tags: readonly string[];
39
+ /** Capability names such as `"keyword"`, `"scoped"`, `"polling"`. */
40
+ readonly capabilities: readonly string[];
41
+ readonly status: "active" | "stub";
42
+ /**
43
+ * Authorized slash-hierarchical source scope strings discovered for this
44
+ * datasource. Scope-capable datasources expose only sources allowed by the
45
+ * trusted scope predicate; unscoped datasources expose their opaque sources.
46
+ */
47
+ readonly sourceScopes: readonly string[];
48
+ }
49
+ /**
50
+ * Caller request narrowing which retrieval methods run.
51
+ *
52
+ * Semantics (unambiguous, deny-widening):
53
+ * - `datasourceIds` omitted ⇒ every authorized datasource method is eligible.
54
+ * - `datasourceIds` present ⇒ ONLY methods of those datasources are eligible,
55
+ * plus the local (non-datasource) methods only when `local === true`.
56
+ * - `local === false` ⇒ no local method is ever eligible.
57
+ * - `methods` present ⇒ intersected with the eligible set; every named method
58
+ * must exist and (for datasource methods) be authorized.
59
+ */
60
+ export interface RetrievalSelection {
61
+ /** Datasource ids to run. Omit to run all authorized datasources. */
62
+ readonly datasourceIds?: readonly string[];
63
+ /** Method names to run, intersected with the datasource/local selection. */
64
+ readonly methods?: readonly string[];
65
+ /** Whether local (non-datasource) methods run. See the semantics above. */
66
+ readonly local?: boolean;
67
+ }
68
+ export type RetrievalSelectionErrorCode = "unknown-method" | "unauthorized-method" | "unknown-datasource" | "unauthorized-datasource";
69
+ /** Thrown when a caller selection names an unknown or unauthorized target. */
70
+ export declare class RetrievalSelectionError extends Error {
71
+ readonly code: RetrievalSelectionErrorCode;
72
+ constructor(code: RetrievalSelectionErrorCode, message: string);
73
+ }
74
+ /**
75
+ * Reduce the registered methods to the ones a selection authorizes to run.
76
+ *
77
+ * The returned list is built entirely from `methods`; a caller cannot conjure a
78
+ * method that is not registered. Datasource methods denied by `ctx` are dropped
79
+ * from the eligible set unconditionally, so they are never invoked. Explicit
80
+ * selections that name an unknown method or an unauthorized/unknown datasource
81
+ * throw {@link RetrievalSelectionError} rather than degrading silently.
82
+ *
83
+ * @param methods Every registered retrieval method.
84
+ * @param ctx Trusted, server-supplied access context.
85
+ * @param selection Caller narrowing request.
86
+ * @param authorizedDatasourceIds Authorized datasource ids from the catalog;
87
+ * used to distinguish an unknown id from an unauthorized one. Method-less
88
+ * authorized datasources belong here and select cleanly (yielding nothing).
89
+ */
90
+ export declare function resolveSelectedMethods(methods: readonly RetrievalMethod[], ctx: DatasourceAccessContext, selection: RetrievalSelection, authorizedDatasourceIds: readonly string[]): RetrievalMethod[];
91
+ /**
92
+ * Authorized datasource ids derived directly from a method set and access
93
+ * context. Used as the fallback catalog for a standalone engine that has no
94
+ * datasource-skill catalog wired in; method-less datasources are unknowable
95
+ * here and therefore treated as unknown.
96
+ */
97
+ export declare function derivedAuthorizedDatasourceIds(methods: readonly RetrievalMethod[], ctx: DatasourceAccessContext): string[];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autorag/librarian",
3
- "version": "2.6.3",
3
+ "version": "2.8.0",
4
4
  "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -21,7 +21,8 @@
21
21
  }
22
22
  },
23
23
  "bin": {
24
- "autorag": "dist/cli/index.js"
24
+ "autorag": "dist/cli/index.js",
25
+ "autorag-mcp": "dist/mcp/index.js"
25
26
  },
26
27
  "files": [
27
28
  "dist",
@@ -35,7 +36,7 @@
35
36
  "access": "public"
36
37
  },
37
38
  "scripts": {
38
- "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",
39
+ "build": "bun build src/index.ts src/core.ts src/cli/index.ts src/mcp/index.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
39
40
  "prepublishOnly": "bun run typecheck && bun run build",
40
41
  "prepare": "bun run build",
41
42
  "test": "node scripts/run-test-files.mjs",
@@ -54,10 +55,12 @@
54
55
  "@earendil-works/pi-ai": "^0.86.1",
55
56
  "@earendil-works/pi-coding-agent": "0.86.1",
56
57
  "@earendil-works/pi-tui": "0.86.1",
58
+ "@modelcontextprotocol/server": "^2.3.0",
57
59
  "@openrouter/sdk": "^1.4.21",
58
60
  "chardet": "^2.2.0",
59
61
  "fast-xml-parser": "^5.11.1",
60
62
  "iconv-lite": "^0.7.3",
63
+ "jev-use": "^0.8.0",
61
64
  "jszip": "^3.10.1",
62
65
  "kordoc": "^4.15.7",
63
66
  "mailparser": "^3.9.20",
@@ -71,11 +74,15 @@
71
74
  },
72
75
  "devDependencies": {
73
76
  "@biomejs/biome": "2.5.14",
77
+ "@modelcontextprotocol/client": "^2.3.0",
74
78
  "@types/mailparser": "^3.4.6",
75
79
  "@types/node": "^26.4.1",
76
80
  "@types/ws": "^8.18.1",
77
81
  "typescript": "^7.0.2",
78
82
  "vitest": "^5.0.0",
79
83
  "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/xlsx-0.20.3.tgz"
84
+ },
85
+ "overrides": {
86
+ "zod": "3.25.76"
80
87
  }
81
88
  }
@@ -47,15 +47,20 @@ refresh is enabled by default and can be disabled with
47
47
  to `workspacePath`) that refresh keeps out of the parsed mirror and MinSync.
48
48
  A folder entry excludes everything under it. Removing an entry and running
49
49
  `autorag refresh --method minsync` indexes the file again. Excluded sources are
50
- recorded as `user-excluded` skips, so they are not reported as stale.
50
+ recorded as `user-excluded` skips, so they are not reported as stale. Jikji
51
+ indexes the source folders directly and is not refreshed here, so AutoRAG also
52
+ drops excluded paths from the `jikji_find` answer pack and the baseline prefetch
53
+ at retrieval time; the on-disk `.jikji_agent_map.md` stays complete, and direct
54
+ file reads remain available.
51
55
 
52
56
  `status` is model-free and path-opaque. `health` resolves the single model,
53
57
  checks credential presence, and normally probes one live completion. If the
54
58
  model, authentication, configuration, or indexes are unhealthy, use
55
59
  `autorag-setup` rather than guessing private provider details.
56
60
 
57
- MinSync and Jikji should normally be healthy. MinSync and Jikji
58
- auto-install on first use by default. If they are missing or stale, run a full
61
+ MinSync and Jikji should normally be healthy. Answering a question never
62
+ builds or installs them: `autorag refresh` auto-installs both by default and
63
+ builds their indexes incrementally. If they are missing or stale, run a full
59
64
  `autorag refresh` or return to setup rather than silently degrading to
60
65
  lexical-only search.
61
66
 
@@ -71,7 +76,10 @@ autorag search "what were the key findings in the Q3 report" --top-k 5 --json --
71
76
 
72
77
  `--json --debug` includes `answer`, numbered `results` (`number`, `title`,
73
78
  `summary`, optional `source`), and `sessionId`. Use that `sessionId` for
74
- feedback. `--json` without `--debug` is only `answer` plus `results`.
79
+ feedback. `--json` without `--debug` is only `answer` plus `results`. Every
80
+ bracketed `[n]` citation in `answer` resolves to a `results[].number` of the
81
+ same response; an unmatched citation is removed and reported as a
82
+ `citation-without-result` diagnostic.
75
83
 
76
84
  To inspect the exact persisted evidence behind numbered results, use:
77
85
 
@@ -98,6 +106,19 @@ AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval,
98
106
  direct source reading as appropriate. If search fails because of model,
99
107
  provider, auth, or timeout problems, diagnose with `autorag health --json`.
100
108
 
109
+ Every search is two-phase: a fast answer, then verification. With Jev on (the
110
+ default, OpenRouter), Jev first routes the question:
111
+
112
+ - General knowledge or small talk is answered directly.
113
+ - Private-data questions use local search; public current facts use web search.
114
+ - A multi-part question is split into up to five parallel search queries.
115
+
116
+ After the fast answer, Jev ends the run if the answer is complete and
117
+ evidence-backed. So `results` may come straight from the fast answer, with no
118
+ verification phase. `--debug` diagnostics show the decision: `query-routed`
119
+ (branch and queries), `follow-up-skipped` (fast answer final), or
120
+ `query-route-fallback` (Jev unavailable, single local search).
121
+
101
122
  Record feedback so retrieval memory can learn. Numbers refer to the returned
102
123
  knowledge units. Supply at least one feedback list:
103
124
 
@@ -87,36 +87,41 @@ Rules:
87
87
 
88
88
  ## 3. Prove searchability
89
89
 
90
- Indexing without retrieval is a failed run. Probe retrieval per datasource with
91
- the model-free path, then once end to end:
90
+ Indexing without retrieval is a failed run. Probe retrieval per datasource
91
+ through the model-free MCP tools, then once end to end:
92
+
93
+ ```text
94
+ autorag.status {}
95
+ autorag.search {"query":"a word that certainly appears","topK":3}
96
+ autorag.search {"query":"recent topic","tags":["discord"],"topK":3}
97
+ autorag.search {"query":"recent mail subject","scope":"/mailcrawl/**","topK":3}
98
+ ```
92
99
 
93
100
  ```bash
94
- autorag lite retrieve "a word that certainly appears" --top-k 3 --json --debug
95
- autorag lite retrieve "recent topic" --tags discord --top-k 3 --json --debug
96
- autorag lite retrieve "recent mail subject" --scope "/mailcrawl/**" --top-k 3 --json --debug
97
101
  autorag search "summarize the collection" --top-k 3 --json --debug
98
102
  ```
99
103
 
100
- - **Always pass `--debug` when diagnosing, and read the diagnostics.** A run
104
+ - **Always read the `diagnostics` returned by MCP `autorag.search`.** A run
101
105
  that silently dropped a whole retrieval method still looks successful, just
102
106
  with fewer results; only the diagnostics name it (`minsync-unavailable`,
103
- `retrieval-method-failed`). `autorag search --json` hides `diagnostics`,
104
- `sessionId`, and per-result evidence unless `--debug` is set. `lite retrieve
105
- --json` always carries the `diagnostics` array, but its human-readable output
106
- hides it without `--debug`.
107
+ `retrieval-method-failed`). The model-backed CLI `autorag search --json`
108
+ hides `diagnostics`, `sessionId`, and per-result evidence unless `--debug` is
109
+ set, so pass `--debug` when diagnosing that path.
107
110
  - A method missing from the returned `method` values means that method
108
111
  contributed nothing. During a full MinSync re-sync this is expected: the
109
112
  store is being rebuilt, `minsync status` reports `NotSynced`, and local-file
110
113
  hits stay absent until it finishes. Confirm with `minsync status` before
111
114
  treating it as a failure, and never kill a running sync to "fix" it.
112
- - `lite retrieve` needs no model, so it isolates retrieval from model failures.
113
- - Use `--tags` / `--scope` to force one datasource; they can only narrow
114
- trusted access, never grant it. A datasource absent from `datasourceAccess`
115
- returns nothing no matter how healthy its store is — fix the config, not the
116
- store.
117
- - `autorag evidence SESSION --json` (session id comes from `--json --debug`)
118
- shows the exact chunk behind a numbered result; use it to confirm a hit is
119
- real and its source is readable.
115
+ - MCP `autorag.search` needs no model, so it isolates retrieval from model
116
+ failures.
117
+ - Use the MCP `tags` / `scope` arguments to force one datasource; they can only
118
+ narrow trusted access, never grant it. A datasource absent from
119
+ `datasourceAccess` returns nothing no matter how healthy its store is — fix
120
+ the config, not the store.
121
+ - `autorag.evidence {"sessionId":"...","resultNumber":N}` shows the exact chunk
122
+ behind a numbered result; use it to confirm a hit is real and its source is
123
+ readable. The CLI `autorag evidence SESSION --json` remains for terminal
124
+ repair.
120
125
  - Local-file hits must map to an absolute, existing path. Datasource hits keep
121
126
  source-native identities such as `/kakao/personal/chunks/42`; those are not
122
127
  filesystem paths and must never be passed to `cat`.
@@ -217,6 +222,10 @@ timer, or Task Scheduler).
217
222
  | `unknown-datasource-skill` | Config name is not a known template | Fix the name or add `"type"` |
218
223
  | `retrieval-method-failed` | One method errored during the query | Read `--debug` diagnostics |
219
224
  | `auth-error` | Credentials missing or rejected | Report the env var name |
225
+ | `query-route-fallback` | Jev routing unavailable (often `OPENROUTER_API_KEY` unset); searched local with the original question | `test -n "$OPENROUTER_API_KEY"`; report the env var name, never its value |
226
+ | `query-decomposition-failed` | Decomposition model call failed; searched the original question | Check `queryDecomposition.model` resolves (`autorag models list --provider openrouter`) |
227
+ | `follow-up-check-fallback` | Jev post-fast-answer check unavailable; the run verified | Same as `query-route-fallback` |
228
+ | `query-routed` / `follow-up-skipped` | Info: Jev's branch and queries / fast answer judged final | None; working as intended |
220
229
 
221
230
  ## Report
222
231