@autorag/librarian 2.7.0 → 2.9.0

package/dist/retrieval/engine.d.ts

@@ -2,28 +2,20 @@
  * 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.
+ * datasource scope 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.
+ * Every configured/connected datasource is searchable without permission
+ * setup. The ordinary query `scope` narrows scope-capable datasource results
+ * after retrieval; local (non-datasource) methods and datasources without
+ * source-scope support pass through untouched.
  */
-import { DatasourceAccessContext, type DatasourceAccessContextOptions } from "../datasource/access-context.js";
 import { RetrievalMethodRegistry } from "./registry.js";
-import type { Reranker } from "./rerank.js";
+import { type Reranker } from "./rerank.js";
+import { type RetrievalSelection } from "./selection.js";
 import type { RetrievalDiagnostic, RetrievalMethod, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface } 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. This is a safety ceiling on
      * merged evidence, not a relevance cut: the merger returns every distinct
@@ -34,13 +26,13 @@ export interface RetrievalEngineOptions {
     /** 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.
+     * Configured datasource ids from the skill catalog, including datasources
+     * that expose no retrieval methods. {@link retrieveSelected} uses this to
+     * tell an unknown datasource id from a known one. When omitted, the engine
+     * derives ids from its registered methods; method-less datasources are then
+     * treated as unknown.
      */
-    readonly isMinSyncBinaryMissing?: () => boolean;
+    readonly datasourceIds?: () => readonly string[];
     /**
      * Optional post-merge reranker. When set, merged results are reordered by
      * the reranker after dedup and score normalization. A reranker failure is
@@ -48,6 +40,11 @@ export interface RetrievalEngineOptions {
      * the engine never silently drops evidence because a reranker was down.
      */
     readonly reranker?: Reranker;
+    /**
+     * Number of merged results kept after reranking when the caller omits `topK`.
+     * Only applies when {@link reranker} is set. @default DEFAULT_RERANK_TOP_N
+     */
+    readonly rerankTopN?: number;
 }
 /**
  * Model-free retrieval pipeline.
@@ -56,7 +53,7 @@ export interface RetrievalEngineOptions {
  * ```
  * methods = registry.list()
  * byMethod = retriever.retrieveWithDiagnostics(methods, query, options)
- * filtered = filter.filter(byMethod, methods, ctx, options.scope)
+ * filtered = filterDatasourceScope(byMethod, methods, options.scope)
  * merged = merger.merge(filtered, { topK, dedup: true })  // distinct chunks, pure duplicates dropped
  * → { results: merged, diagnostics }
  * ```
@@ -73,18 +70,15 @@ export interface RetrievalEngineOptions {
 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;
+    private readonly datasourceIdsProvider;
     private readonly reranker;
+    private readonly rerankTopN;
     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.
@@ -125,22 +119,18 @@ export declare class RetrievalEngine {
         unsearched: RetrievalUnsearchedSurface[];
     }>;
     /**
-     * Post-check for MinSync binary-missing diagnostic.
+     * Run a selected subset of the registered methods — parallel retrieve,
+     * scope filter, merge — and return merged results with diagnostics.
      *
-     * 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`). The
-     * same check reports the MinSync surface as unsearched, so a caller reading
-     * only the skip report still learns that local sources were not queried.
-     */
-    private appendMinSyncUnavailable;
-    /**
-     * 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.
+     * Unlike {@link retrieve}, selection happens BEFORE any backend is invoked:
+     * the eligible method list is reduced first, so an unselected datasource
+     * backend is never spawned. Unknown method or datasource selections throw
+     * {@link RetrievalSelectionError}. The ordinary query `scope` still narrows
+     * results after retrieval.
      */
-    private accessContextFor;
+    retrieveSelected(query: string, selection?: RetrievalSelection, options?: RetrievalOptions): Promise<{
+        results: RetrievalResult[];
+        diagnostics: RetrievalDiagnostic[];
+        unsearched: RetrievalUnsearchedSurface[];
+    }>;
 }

package/dist/retrieval/index.d.ts

@@ -1,8 +1,10 @@
+export { bm25Scores, tokenize } from "./bm25.js";
 export { RetrievalEngine, type RetrievalEngineOptions } from "./engine.js";
 export type { MergeOptions } from "./merger.js";
 export { ParallelRetriever, ResultMerger } from "./merger.js";
 export { RetrievalMethodRegistry } from "./registry.js";
-export { type CreateRerankerOptions, createReranker, DEFAULT_RERANK_API_KEY_ENV, DEFAULT_RERANK_MODEL, DEFAULT_RERANK_PROVIDER, OpenRouterReranker, type OpenRouterRerankerOptions, type Reranker, type RerankerDescriptor, type RerankOptions, SUPPORTED_RERANK_PROVIDERS, } from "./rerank.js";
+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";
 export { matchesVirtualPathScope, normalizeVirtualPath, normalizeVirtualPathScope, virtualPathScopeToRegExp, } from "./scope.js";
+export { type DatasourceCatalogEntry, derivedDatasourceIds, type RetrievalSelection, RetrievalSelectionError, type RetrievalSelectionErrorCode, resolveSelectedMethods, } from "./selection.js";
 export { describeRetrievalError, groupUnsearchedSurfaces, MINSYNC_SURFACE, type RetrievalSkip, retrievalSurfaceFor, } from "./skip.js";
 export type { CuratedResult, NumberedResult, RetrievalDiagnostic, RetrievalDiagnosticCode, RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult, RetrievalUnsearchedSurface, RetrievalWithDiagnostics, } from "./types.js";

package/dist/retrieval/merger.d.ts

@@ -30,6 +30,12 @@ export interface MergeOptions {
 export declare class ResultMerger {
     merge(results: Map<string, RetrievalResult[]>, options: MergeOptions): RetrievalResult[];
 }
+/**
+ * Runs every method in parallel. A method that throws is skipped and the
+ * others still answer, with one exception: {@link MinSyncRequiredError} means
+ * the required MinSync is absent, so the whole retrieval fails instead of
+ * returning an answer that silently lacks its content search.
+ */
 export declare class ParallelRetriever {
     retrieve(methods: RetrievalMethod[], query: string, options: RetrievalOptions): Promise<Map<string, RetrievalResult[]>>;
     /**

package/dist/retrieval/rerank.d.ts

@@ -1,7 +1,7 @@
 /**
  * Reranker seam — a post-retrieval reordering stage over merged evidence.
  *
- * The retrieval pipeline (registry → ParallelRetriever → DatasourceResultFilter
+ * The retrieval pipeline (registry → ParallelRetriever → filterDatasourceScope
  * → ResultMerger) produces a scored candidate list. A reranker reorders that
  * list with a dedicated relevance model. The default implementation talks to
  * OpenRouter's rerank router through the OpenRouter TypeScript SDK.
@@ -18,6 +18,8 @@ export declare const DEFAULT_RERANK_MODEL = "voyageai/rerank-3-lite";
 export declare const DEFAULT_RERANK_PROVIDER = "openrouter";
 /** Default environment variable holding the OpenRouter API key. */
 export declare const DEFAULT_RERANK_API_KEY_ENV = "OPENROUTER_API_KEY";
+/** Default number of merged chunks kept after reranking. */
+export declare const DEFAULT_RERANK_TOP_N = 25;
 /** Rerank providers {@link createReranker} can build. */
 export declare const SUPPORTED_RERANK_PROVIDERS: readonly string[];
 /** Static description of a reranker, used for diagnostics and inspection. */
@@ -26,7 +28,7 @@ export interface RerankerDescriptor {
     readonly name: string;
     /** Provider id (e.g. `openrouter`). */
     readonly provider: string;
-    /** Wire model id (e.g. `cohere/rerank-4-fast`). */
+    /** Wire model id (e.g. `voyageai/rerank-3`). */
     readonly model: string;
     /** Whether the reranker has everything it needs to run (credentials, config). */
     readonly available: boolean;

package/dist/retrieval/selection.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Selection gating for the retrieval pipeline.
+ *
+ * `searchSelected` lets a caller narrow a search to specific datasources,
+ * specific methods, or the local (non-datasource) surfaces *before* any backend
+ * is invoked. This module owns that narrowing so the engine can reuse its
+ * existing parallel-retrieve / scope-filter / merge chain on the reduced
+ * method list instead of fanning out to every backend and filtering afterwards.
+ *
+ * Every configured datasource is searchable without permission setup. A
+ * caller-supplied selection can only *narrow* the registered method set: it can
+ * never add a method that is not registered. Unknown method or datasource names
+ * are rejected with a typed error, never silently resolved.
+ */
+import type { RetrievalMethod } from "./types.js";
+/**
+ * Model-free, credential-free descriptor of one configured datasource, for
+ * catalog/listing surfaces. Carries no credentials, config paths, or raw
+ * instance metadata — only the identity, descriptive tags, and the opaque
+ * source scope strings the datasource exposes.
+ */
+export interface DatasourceCatalogEntry {
+    /** Stable datasource id, e.g. `"kakao"`. */
+    readonly datasourceId: string;
+    /** Skill name, e.g. `"kakao"`. */
+    readonly name: string;
+    /** Skill kind, e.g. `"chat"` or `"chat-export"`. */
+    readonly type: string;
+    /** Human-readable description. */
+    readonly description: string;
+    /** Descriptive tags (metadata only). */
+    readonly tags: readonly string[];
+    /** Capability names such as `"keyword"`, `"scoped"`, `"polling"`. */
+    readonly capabilities: readonly string[];
+    readonly status: "active" | "stub";
+    /**
+     * Slash-hierarchical source scope strings discovered for this datasource.
+     * Scope-capable datasources expose their instance source scopes; unscoped
+     * datasources expose their opaque sources.
+     */
+    readonly sourceScopes: readonly string[];
+}
+/**
+ * Caller request narrowing which retrieval methods run.
+ *
+ * Semantics (unambiguous, narrowing-only):
+ *  - `datasourceIds` omitted ⇒ every datasource method is eligible.
+ *  - `datasourceIds` present ⇒ ONLY methods of those datasources are eligible,
+ *    plus the local (non-datasource) methods only when `local === true`.
+ *  - `local === false` ⇒ no local method is ever eligible.
+ *  - `methods` present ⇒ intersected with the eligible set; every named method
+ *    must exist.
+ */
+export interface RetrievalSelection {
+    /** Datasource ids to run. Omit to run all configured datasources. */
+    readonly datasourceIds?: readonly string[];
+    /** Method names to run, intersected with the datasource/local selection. */
+    readonly methods?: readonly string[];
+    /** Whether local (non-datasource) methods run. See the semantics above. */
+    readonly local?: boolean;
+}
+export type RetrievalSelectionErrorCode = "unknown-method" | "unknown-datasource";
+/** Thrown when a caller selection names an unknown method or datasource. */
+export declare class RetrievalSelectionError extends Error {
+    readonly code: RetrievalSelectionErrorCode;
+    constructor(code: RetrievalSelectionErrorCode, message: string);
+}
+/**
+ * Reduce the registered methods to the ones a selection authorizes to run.
+ *
+ * The returned list is built entirely from `methods`; a caller cannot conjure a
+ * method that is not registered. Explicit selections that name an unknown
+ * method or an unknown datasource throw {@link RetrievalSelectionError} rather
+ * than degrading silently.
+ *
+ * @param methods       Every registered retrieval method.
+ * @param selection     Caller narrowing request.
+ * @param datasourceIds Configured datasource ids (from the catalog), used to
+ *   distinguish a known datasource from an unknown one. Method-less
+ *   datasources belong here and select cleanly (yielding nothing).
+ */
+export declare function resolveSelectedMethods(methods: readonly RetrievalMethod[], selection: RetrievalSelection, datasourceIds: readonly string[]): RetrievalMethod[];
+/**
+ * Configured datasource ids derived directly from a method set. Used as the
+ * fallback catalog for a standalone engine that has no datasource-skill catalog
+ * wired in; method-less datasources are unknowable here and therefore treated
+ * as unknown.
+ */
+export declare function derivedDatasourceIds(methods: readonly RetrievalMethod[]): string[];

package/dist/retrieval/types.d.ts

@@ -18,15 +18,13 @@ export interface RetrievalOptions {
     topK?: number;
     scope?: string;
     filters?: Record<string, unknown>;
-    allowedTags?: readonly string[];
-    allowedScopes?: readonly string[];
     signal?: AbortSignal;
 }
 export interface RetrievalMethod {
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
-export type RetrievalDiagnosticCode = "retrieval-method-failed" | "minsync-unavailable" | "rerank-failed";
+export type RetrievalDiagnosticCode = "retrieval-method-failed" | "rerank-failed";
 /**
  * A retrieval surface (local MinSync files or one datasource) that was not
  * searched for this query. Reported next to partial results so a caller that

package/dist/web/search/format.d.ts

@@ -18,8 +18,11 @@ export declare const WEB_SEARCH_SYSTEM_PROMPT = "Web research assistant: accurat
 export declare const WEB_SEARCH_TOOL_DESCRIPTION = "Web search: current information beyond knowledge cutoff.\n\n- SHOULD prefer primary sources (papers, official docs); corroborate key claims with multiple sources.\n- MUST link cited sources in final response.\n- NEVER use for programmatically accessible content or known URLs (GitHub repos/issues, known arXiv papers, Wikipedia pages, official docs) \u2014 use web_fetch on the URL directly.\n- `query`: every provider supports Google-style `site:`/`-site:`, `after:`/`before:` (YYYY-MM-DD), `inurl:`, `intitle:`, `filetype:`, `\"exact phrase\"`, `-term`, `OR`. Map constraints to native filters when available; otherwise results are filtered leniently. If a constraint matches nothing, it is relaxed and reported; zero results are never forced.";
 /** Format an age in seconds as a compact relative string ("45s", "2h", "3d"). */
 export declare function formatAge(ageSeconds: number | undefined): string;
-/** Format response for LLM consumption. `notes` lead the output (e.g. relaxed-constraint warnings). */
-export declare function formatForLLM(response: SearchResponse, notes?: readonly string[]): string;
+/**
+ * Format response for LLM consumption. `notes` lead the output (e.g. relaxed-constraint warnings).
+ * `sourceLabels` replaces the positional `[n]` of each source (e.g. `e3`) so the model can cite it by id.
+ */
+export declare function formatForLLM(response: SearchResponse, notes?: readonly string[], sourceLabels?: readonly string[]): string;
 /**
  * `true` when the response carries an actual result the caller can read: an
  * answer, a source, or a citation. Search-attempt metadata (`searchQueries`,

package/dist/web/search/index.d.ts

@@ -1,5 +1,5 @@
 import type { ModelNativeSearchAuth } from "./model-auth.js";
-import { type SearchProviderId, type SearchResponse } from "./types.js";
+import { type SearchProviderId, type SearchResponse, type SearchSource } from "./types.js";
 export interface WebSearchQueryParams {
     query: string;
     recency?: "day" | "week" | "month" | "year";
@@ -38,6 +38,12 @@ export interface WebSearchExecuteOptions {
     modelAuth?: ModelNativeSearchAuth;
     /** Transport injection for tests/proxies; forwarded to providers that accept it. */
     fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Called with the sources that survived filtering, just before formatting.
+     * Returns one label per source (e.g. an evidence id) that replaces its
+     * positional `[n]` in the output the model reads.
+     */
+    labelSources?: (sources: readonly SearchSource[]) => readonly string[];
 }
 /** Execute a web search through the provider fallback chain. */
 export declare function executeWebSearch(params: WebSearchQueryParams, options?: WebSearchExecuteOptions): Promise<WebSearchExecuteResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,8 @@
     }
   },
   "bin": {
-    "autorag": "dist/cli/index.js"
+    "autorag": "dist/cli/index.js",
+    "autorag-mcp": "dist/mcp/index.js"
   },
   "files": [
     "dist",
@@ -35,7 +36,7 @@
     "access": "public"
   },
   "scripts": {
-    "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",
+    "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",
     "prepublishOnly": "bun run typecheck && bun run build",
     "prepare": "bun run build",
     "test": "node scripts/run-test-files.mjs",
@@ -50,14 +51,16 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "^0.86.1",
-    "@earendil-works/pi-ai": "^0.86.1",
-    "@earendil-works/pi-coding-agent": "0.86.1",
-    "@earendil-works/pi-tui": "0.86.1",
+    "@earendil-works/pi-agent-core": "^1.1.0",
+    "@earendil-works/pi-ai": "^1.1.0",
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-tui": "1.1.0",
+    "@modelcontextprotocol/server": "^2.3.0",
     "@openrouter/sdk": "^1.4.21",
     "chardet": "^2.2.0",
     "fast-xml-parser": "^5.11.1",
     "iconv-lite": "^0.7.3",
+    "jev-use": "^0.8.0",
     "jszip": "^3.10.1",
     "kordoc": "^4.15.7",
     "mailparser": "^3.9.20",
@@ -71,6 +74,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",
+    "@modelcontextprotocol/client": "^2.3.0",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^26.4.1",
     "@types/ws": "^8.18.1",

package/skills/autorag/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autorag
-description: Search, summarize, compare, and answer questions from an already configured AutoRAG librarian over local documents and authorized datasources. Use when the user asks AutoRAG to search PDFs, wikis, notes, or a knowledge base. Use autorag-setup for install, model, roots, indexing, or datasource changes.
+description: Search, summarize, compare, and answer questions from an already configured AutoRAG librarian over local documents and configured datasources. Use when the user asks AutoRAG to search PDFs, wikis, notes, or a knowledge base. Use autorag-setup for install, model, roots, indexing, or datasource changes.
 license: MIT
 ---
 
@@ -8,7 +8,7 @@ license: MIT
 
 Use this skill when AutoRAG is already configured and the user asks to search,
 summarize, compare, or answer questions from local PDFs, wikis, notes, research
-papers, knowledge bases, or authorized datasources.
+papers, knowledge bases, or configured datasources.
 
 AutoRAG is the specialized librarian agent. One configured model plans the
 search, calls MinSync, Jikji, datasource, and filesystem tools, reads
@@ -47,31 +47,39 @@ refresh is enabled by default and can be disabled with
 to `workspacePath`) that refresh keeps out of the parsed mirror and MinSync.
 A folder entry excludes everything under it. Removing an entry and running
 `autorag refresh --method minsync` indexes the file again. Excluded sources are
-recorded as `user-excluded` skips, so they are not reported as stale.
+recorded as `user-excluded` skips, so they are not reported as stale. Jikji
+indexes the source folders directly and is not refreshed here, so AutoRAG also
+drops excluded paths from the `jikji_find` answer pack and the baseline prefetch
+at retrieval time; the on-disk `.jikji_agent_map.md` stays complete, and direct
+file reads remain available.
 
 `status` is model-free and path-opaque. `health` resolves the single model,
 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.
 
-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
+MinSync and Jikji should normally be healthy. Answering a question never
+builds or installs them: `autorag refresh` auto-installs both by default and
+builds their indexes incrementally. If they are missing or stale, run a full
 `autorag refresh` or return to setup rather than silently degrading to
 lexical-only search.
 
 ## Search
 
-Prefer `--json --debug` when another agent will consume the result or record
-feedback. `--json` alone omits `sessionId`. `--debug` adds session/diagnostics
-fields and does not print filesystem paths.
+Prefer `--json --debug` when another agent will consume the result.
+`--json` alone omits `sessionId`. `--debug` adds session/diagnostics fields and
+does not print filesystem paths.
 
 ```bash
 autorag search "what were the key findings in the Q3 report" --top-k 5 --json --debug
 ```
 
 `--json --debug` includes `answer`, numbered `results` (`number`, `title`,
-`summary`, optional `source`), and `sessionId`. Use that `sessionId` for
-feedback. `--json` without `--debug` is only `answer` plus `results`.
+`summary`, optional `source`), and `sessionId`. `--json` without `--debug` is
+only `answer` plus `results`. Every
+bracketed `[n]` citation in `answer` resolves to a `results[].number` of the
+same response; an unmatched citation is removed and reported as a
+`citation-without-result` diagnostic.
 
 To inspect the exact persisted evidence behind numbered results, use:
 
@@ -85,10 +93,8 @@ ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber`,
 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.
+- `--scope` narrows datasource retrieval to a requested sub-path (ordinary
+  per-query filtering).
 - `--json` is required for programmatic consumption.
 - `--debug` is required for `sessionId` and diagnostics in search output.
 - `autorag evidence` is the detailed source/chunk inspection path.
@@ -98,12 +104,27 @@ AutoRAG. The search loop can use Jikji, MinSync lexical/vector/hybrid retrieval,
 direct source reading as appropriate. If search fails because of model,
 provider, auth, or timeout problems, diagnose with `autorag health --json`.
 
-Record feedback so retrieval memory can learn. Numbers refer to the returned
-knowledge units. Supply at least one feedback list:
-
-```bash
-autorag feedback <sessionId> --useful 1,3 --not-useful 2 --json
-```
+Every search is two-phase: a fast answer, then verification. With Jev on (the
+default, OpenRouter), Jev first routes the question:
+
+- General knowledge or small talk is answered directly.
+- A request to view or change AutoRAG's own settings (model, providers,
+  datasources) is handled by the agent itself: it loads the setup skill, edits
+  the active config, verifies it, and reports what changed. The running agent
+  keeps its startup model; changes apply to the next `autorag` launch.
+- Private-data questions use local search; public current facts use web search.
+- A multi-part question is split into up to five parallel search queries.
+- On local search, Jev also picks which registered datasources (Slack,
+  Discord, KakaoTalk, email, ...) to search before the fast answer, from each
+  datasource's description and where similar past questions were answered;
+  their chunks are reranked together with local file evidence.
+
+After the fast answer, Jev ends the run if the answer is complete and
+evidence-backed. So `results` may come straight from the fast answer, with no
+verification phase. `--debug` diagnostics show the decision: `query-routed`
+(branch and queries), `datasources-selected` (datasources searched or skipped,
+with probabilities), `follow-up-skipped` (fast answer final), or
+`query-route-fallback` (Jev unavailable, single local search).
 
 ## Maintenance
 
@@ -144,9 +165,8 @@ Never target source documents. `memory inspect` is read-only and path-opaque.
 - Never expose provider credentials or authentication payloads.
 - Never invent provider identities or model ids.
 - A Pi-usable subscription is valid; a subscription Pi cannot invoke is not.
-- Preserve real source mapping and numbered feedback identifiers.
-- Prefer `--json --debug` when another agent consumes search output or will
-  call `autorag feedback`.
+- Preserve real source mapping.
+- Prefer `--json --debug` when another agent consumes search output.
 - Do not invent CLI commands. `autorag --help` is the command list of record,
   including the shipped `setup`, `gateway`, `models`, `serve`, `p2p`, `tui`, and `lite`
   commands. `autorag <command> --help` prints that command's own flags, and

package/skills/autorag-doctor/SKILL.md

@@ -43,7 +43,7 @@ autorag gateway status --format json
 
 Config lives at `--config`, `AUTORAG_CONFIG`, `$AUTORAG_HOME/config.json`, or
 `~/.autorag/config.json`. Read `searchPaths`, `workspacePath`, `minSync`,
-`jikji`, `datasources`, and `datasourceAccess` before changing anything.
+`jikji`, and `datasources` before changing anything.
 
 If the CLI itself is missing or the config does not exist, stop and run the
 `autorag-setup` skill first — doctor repairs an existing install, it does not
@@ -87,36 +87,42 @@ Rules:
 
 ## 3. Prove searchability
 
-Indexing without retrieval is a failed run. Probe retrieval per datasource with
-the model-free path, then once end to end:
+Indexing without retrieval is a failed run. Probe retrieval per datasource
+through the model-free MCP tools, then once end to end:
+
+```text
+autorag.status {}
+autorag.search {"query":"a word that certainly appears","topK":3}
+autorag.search {"query":"recent topic","datasourceIds":["discord"],"topK":3}
+autorag.search {"query":"recent mail subject","scope":"/mailcrawl/**","topK":3}
+```
 
 ```bash
-autorag lite retrieve "a word that certainly appears" --top-k 3 --json --debug
-autorag lite retrieve "recent topic" --tags discord --top-k 3 --json --debug
-autorag lite retrieve "recent mail subject" --scope "/mailcrawl/**" --top-k 3 --json --debug
 autorag search "summarize the collection" --top-k 3 --json --debug
 ```
 
-- **Always pass `--debug` when diagnosing, and read the diagnostics.** A run
+- **Always read the `diagnostics` returned by MCP `autorag.search`.** A run
   that silently dropped a whole retrieval method still looks successful, just
-  with fewer results; only the diagnostics name it (`minsync-unavailable`,
-  `retrieval-method-failed`). `autorag search --json` hides `diagnostics`,
-  `sessionId`, and per-result evidence unless `--debug` is set. `lite retrieve
-  --json` always carries the `diagnostics` array, but its human-readable output
-  hides it without `--debug`.
+  with fewer results; only the diagnostics name it (`retrieval-method-failed`).
+  The model-backed CLI `autorag search --json`
+  hides `diagnostics`, `sessionId`, and per-result evidence unless `--debug` is
+  set, so pass `--debug` when diagnosing that path.
 - A method missing from the returned `method` values means that method
   contributed nothing. During a full MinSync re-sync this is expected: the
   store is being rebuilt, `minsync status` reports `NotSynced`, and local-file
   hits stay absent until it finishes. Confirm with `minsync status` before
   treating it as a failure, and never kill a running sync to "fix" it.
-- `lite retrieve` needs no model, so it isolates retrieval from model failures.
-- Use `--tags` / `--scope` to force one datasource; they can only narrow
-  trusted access, never grant it. A datasource absent from `datasourceAccess`
-  returns nothing no matter how healthy its store is — fix the config, not the
-  store.
-- `autorag evidence SESSION --json` (session id comes from `--json --debug`)
-  shows the exact chunk behind a numbered result; use it to confirm a hit is
-  real and its source is readable.
+- MCP `autorag.search` needs no model, so it isolates retrieval from model
+  failures.
+- Use MCP `datasourceIds` to select configured connections before retrieval;
+  `scope` narrows results within scope-capable datasources. Discover connection
+  IDs with `autorag.datasources.list`; descriptor tags are metadata only, not
+  search filters. Every configured connection is searchable — if one returns
+  nothing, investigate its native store, connector, or the query itself.
+- `autorag.evidence {"sessionId":"...","resultNumber":N}` shows the exact chunk
+  behind a numbered result; use it to confirm a hit is real and its source is
+  readable. The CLI `autorag evidence SESSION --json` remains for terminal
+  repair.
 - Local-file hits must map to an absolute, existing path. Datasource hits keep
   source-native identities such as `/kakao/personal/chunks/42`; those are not
   filesystem paths and must never be passed to `cat`.
@@ -192,13 +198,16 @@ timer, or Task Scheduler).
   no `"type"`. It is skipped, not fatal — fix the name or add `"type"`.
 - `datasource-index-failed` / `sync-failed`: the backing CLI errored. Run that
   CLI's own check from the table above and fix it there.
-- `minsync-unavailable` / `jikji-unavailable`: the binary is missing and
-  auto-install failed. Both install through cargo; verify the Rust toolchain,
-  then `autorag refresh --method minsync` to retry.
+- A missing MinSync binary is not a diagnostic: `autorag search`, `autorag refresh`
+  and MCP tools fail with `MinSync is required ...` and a non-zero exit. Install it
+  (`cargo install minsync`) or leave `minSync.autoInstall` on, then retry.
+- `jikji-unavailable`: the binary is missing and auto-install failed. It
+  installs through cargo; verify the Rust toolchain, then `autorag refresh --method jikji` to retry.
 - `auth-error` / `rate-limited`: model or datasource credentials. Report the
   missing environment-variable **name** and let the user supply it.
-- A datasource configured but not listed in `datasourceAccess.allowedTags` /
-  `allowedScopes` is default-denied and invisible to search. Add it there.
+- A configured datasource that returns nothing is a native store, connector, or
+  query problem — every configured connection is searchable. Run its native
+  check from the table above and fix it there.
 
 ## Diagnostic codes
 
@@ -206,7 +215,7 @@ timer, or Task Scheduler).
 |---|---|---|
 | `stale-index` | Sources changed since last refresh | `autorag refresh --method parsed,minsync` |
 | `index-not-ready` | Index missing or never built | `autorag refresh --json` |
-| `minsync-unavailable` | MinSync binary missing or install failed | Check cargo, retry refresh |
+| `minsync-sync-failed` | MinSync indexing failed; the message carries MinSync's own reason | Fix the reported cause, then `autorag refresh --method minsync` |
 | `jikji-unavailable` | Jikji binary missing or install failed | Check cargo, retry refresh |
 | `everything-index-failed` | Windows Everything instance could not start or index; message carries ES exit code and stderr | Fix the reported cause, `autorag refresh --method everything --json` |
 | `embedding-identity-mismatch` | Indexed vectors use a different embedder | `autorag index rebuild --method minsync` |
@@ -217,6 +226,11 @@ timer, or Task Scheduler).
 | `unknown-datasource-skill` | Config name is not a known template | Fix the name or add `"type"` |
 | `retrieval-method-failed` | One method errored during the query | Read `--debug` diagnostics |
 | `auth-error` | Credentials missing or rejected | Report the env var name |
+| `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 |
+| `query-decomposition-failed` | Decomposition model call failed; searched the original question | Check `queryDecomposition.model` resolves (`autorag models list --provider openrouter`) |
+| `follow-up-check-fallback` | Jev post-fast-answer check unavailable; the run verified | Same as `query-route-fallback` |
+| `datasource-selection-fallback` | Jev datasource check unavailable; no datasource was searched before the fast answer | Same as `query-route-fallback` |
+| `query-routed` / `datasources-selected` / `follow-up-skipped` | Info: Jev's branch and queries / datasources searched and skipped / fast answer judged final | None; working as intended. A datasource that is never selected usually needs a clearer `description` in the config |
 
 ## Report