@autorag/librarian 2.12.0 → 2.13.0

package/README.md

@@ -461,7 +461,9 @@ mirrored are kept and not re-parsed on the next run. `onProgress` reports `parse
 (`processed`/`total` are files, `currentVirtualPath` is the file about to be processed) and
 `datasources` (`processed`/`total` are datasource skills). During the parse phase
 `.autorag/refresh-progress.json` also carries the running `sourceFiles.total` and
-`parsedCounts`. Without these options a refresh behaves as before.
+`parsedCounts`, refreshed every 25 files rather than per file. The marker is replaced with a
+retried rename (an in-place overwrite if a reader keeps the destination held, as on Windows).
+Without these options a refresh behaves as before.
 
 ---
 
@@ -601,7 +603,10 @@ and `skills/autorag-setup` only when the agent should also drive the
 model-backed librarian, and `skills/autorag-doctor` for diagnostics. Other
 agents read their own skill directories; copy the same setup folder there and
 reload the agent session so it picks up the MCP registration instructions.
-Do not copy or retain the removed `autorag-lite-search` skill.
+Do not copy or retain the removed `autorag-lite-search` skill. The package also
+ships `internal-skills/`, which holds the librarian's own turn rules (for
+example `internal-skills/organize/`) — those are never parent-agent skills, so
+do not copy them into another agent.
 
 ### Quick Agent Workflow
 
@@ -730,7 +735,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 - **[Telegram Remote Control](docs/telegram.md):** Ask the librarian from a Telegram chat through a running `autorag tui --telegram` session: setup, commands, and keeping it alive.
 - **[Datasource Skills Reference](docs/datasource-skills.md):** Full configuration contracts, connection aliases, and connector options.
 - **[Apple Calendar & Reminders via EventKit MCP](docs/eventkit-mcp.md):** macOS-only: read Calendar events and Reminders (Google/iCloud/Exchange accounts already in Calendar.app) by running `mcp-server-apple-events` beside `autorag-mcp`. Live, read-only; not indexed.
-- **[Jev Decisions](docs/jev-decisions.md):** Jev query pipeline, **on by default** via Dazzi Models when signed in (OpenRouter otherwise): it routes each question to a direct answer (intrinsic knowledge), local search (everything needing more information; web search is left to the agent after the fast answer), `organize` (move, rename, convert, or sort files and folders), or `extra` (any other action such as committing code; no retrieval), splits multi-part questions into up to five parallel searches (`dazzi/openai/gpt-6-luna` when signed in, else `openrouter/qwen/qwen3.7-flash`), picks which registered datasources to search before the fast answer, and ends the run after the fast answer when that answer is complete. Also covers the `jev` judgment tool, backends (OpenRouter, TypeSafe, Vercel AI Gateway), and how to opt out.
+- **[Jev Decisions](docs/jev-decisions.md):** Jev query pipeline, **on by default** via Dazzi Models when signed in (OpenRouter otherwise): it routes each question to local search (everything needing more information, including the public web when the question needs recent public facts), `extra` (a knowledge answer or any other action such as committing code; one turn with every tool, no retrieval), `organize` (move, rename, convert, or sort files and folders), or its own `config` branch, and keeps a weakly-favored non-local verdict on local search through a 0.75 confidence floor. It also splits multi-part questions into up to five parallel searches (`dazzi/openai/gpt-6-luna` when signed in, else `openrouter/qwen/qwen3.7-flash`), picks which registered datasources to search before the fast answer, and ends the run after the fast answer when that answer is complete. Also covers the `jev` judgment tool, backends (OpenRouter, TypeSafe, Vercel AI Gateway), and how to opt out.
 - **[Manual QA & Datasource Test Harnesses](docs/manual-qa-datasources.md):** Real-world testing guides for Discord, KakaoTalk, Slack, Notion, and email.
 - **[Supply Chain Security & License Audits](docs/supply-chain.md):** Software bill of materials (SBOM) and dependency gate policies.
 - **[Competitive Landscape Study](docs/competitive-landscape-2026-09.md):** In-depth analysis of why in-place federation outperforms centralized RAG.

package/dist/agent/agent.d.ts

@@ -21,6 +21,7 @@ import { type DatasourceAgentSkill } from "./datasource-skill.js";
 import { type ScanDuplicateDocumentsDetails } from "./dupey-tool.js";
 import { type JevToolOptions } from "./jev-extension.js";
 import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
+import { type PackagedAgentSkill } from "./packaged-skill.js";
 import { PermissionController, type PermissionMode } from "./permission-gate.js";
 import { type AutoRAGPiInteractiveRuntime, type AutoRAGPiSession } from "./pi-session.js";
 import { type RefreshProgressCounts, type RefreshProgressPhase } from "./refresh-progress.js";
@@ -268,8 +269,9 @@ export interface AutoRAGAgentOptions {
     /**
      * Jev (TypeSafe's judgment model: typed questions in, calibrated
      * probabilities out). When set, the two-phase search asks Jev before the
-     * fast answer whether the question is answerable from intrinsic knowledge
-     * (direct answer) or needs local search, and whether to decompose it; after the fast answer, whether
+     * fast answer which branch handles the question (local search, file
+     * organization, an extra task, or — in a local host — its own configuration)
+     * and whether to decompose it; after the fast answer, whether
      * verification is needed. It also exposes the `jev` tool.
      *
      * The CLI config enables this by default on OpenRouter (`buildAgentOptions`
@@ -297,6 +299,12 @@ export interface AutoRAGAgentOptions {
      * message.
      */
     selfConfig?: SelfConfigOptions;
+    /**
+     * Override for the packaged `organize` skill file that the Jev `organize`
+     * branch loads into its turn; defaults to the packaged skill. Present for a
+     * host that ships its own organize rules, and for tests.
+     */
+    organizeSkillPath?: string;
     /**
      * Question decomposition used by the Jev query pipeline. `model` (with its
      * `apiKey`) is the LLM that splits one question into at most five search
@@ -494,6 +502,8 @@ export declare class AutoRAGAgent {
     private readonly permissionGate;
     /** Self-configuration, enabled only with Jev on a local session. */
     private readonly selfConfig;
+    /** Override for the packaged organize skill the `organize` branch loads; undefined keeps the packaged one. */
+    private readonly organizeSkillPath;
     private readonly queryDecompositionModel;
     /** Web search options for the agent's `web_search` / `web_fetch` tools; undefined when web tools are off. */
     private readonly webSearchOptions;
@@ -716,39 +726,52 @@ export declare class AutoRAGAgent {
     private shouldFollowUp;
     /**
      * Jev query pipeline, run before the fast answer. Jev picks the branch
-     * (direct answer or local search) and whether the question
-     * needs decomposition; a "yes" splits it into at most five search queries
-     * with the configured decomposition model (default: the session model). On
-     * the local branch, Jev also judges, per registered datasource, whether it
-     * must be searched (in parallel with decomposition). Without Jev, and on any
-     * routing failure, this is today's single local search for the original
-     * question with no datasource search.
+     * (local search, file organization, an extra task, AutoRAG configuration)
+     * and whether the question needs decomposition; a "yes" splits it into at
+     * most five search queries with the configured decomposition model
+     * (default: the session model). On the local branch, Jev also judges, per
+     * registered datasource, whether it must be searched (in parallel with
+     * decomposition). Without Jev, and on any routing failure, this is today's
+     * single local search for the original question with no datasource search.
+     * A non-local branch that misses the confidence floor is not a failure: it
+     * becomes a full local plan, decomposition and datasource check included.
      */
     private planQuery;
     /**
      * Jev datasource check for the local branch: one `noul` per configured
-     * datasource that has retrieval methods, with where similar past questions
-     * were answered (from retrieval memory) in the state. Returns the ids to
-     * search with every query before the rerank; a failed check searches none.
+     * datasource that has retrieval methods, plus the public web when its tools
+     * are enabled, with where similar past questions were answered (from
+     * retrieval memory) in the state. Returns the datasource ids and whether the
+     * web is to be searched with every query before the rerank; a failed check
+     * searches neither.
      */
     private selectSearchDatasources;
     /**
-     * Baseline local evidence for the fast answer. Jikji, MinSync, and every
-     * Jev-selected datasource run for every search query in parallel (MinSync
-     * itself queues per workspace), the per-query hits are interleaved and
-     * deduplicated into one pool, and that pool is reranked against the
-     * original question.
+     * Baseline local evidence for the fast answer. Jikji, MinSync, every
+     * Jev-selected datasource, and (when Jev selected it) one web search run for
+     * every search query in parallel (MinSync itself queues per workspace), the
+     * per-query hits are interleaved and deduplicated into one pool, and that
+     * pool is reranked against the original question.
      */
     private prefetchInitialRetrievalContext;
+    /**
+     * One web search for the baseline, on the same provider chain, ordering, and
+     * credentials as the `web_search` tool. Hits carry the URL as their source
+     * and the title plus snippet as their content, so they merge, rerank, and
+     * register like any other candidate. A failure contributes no evidence and
+     * is reported by the caller; a steer abort is the user stopping the search,
+     * not a failure.
+     */
+    private prefetchWebSearch;
     /**
      * Rerank the pre-fast-answer baseline pool — Jikji answer paths, MinSync
-     * chunks, and Jev-selected datasource chunks — down to the configured
-     * `rerank.topN`. With decomposition the pool merges every search query's
-     * hits (interleaved), capped at the same per-source sizes as a single query
-     * so the rerank request does not grow with the query count. Returns
-     * `undefined` when reranking is disabled or the pool is empty. A configured
-     * reranker that is unavailable, throws, or returns nothing for a non-empty
-     * pool throws, so the caller can report it and fall back.
+     * chunks, Jev-selected datasource chunks, and prefetched web hits — down to
+     * the configured `rerank.topN`. With decomposition the pool merges every
+     * search query's hits (interleaved), capped at the same per-source sizes as a
+     * single query so the rerank request does not grow with the query count.
+     * Returns `undefined` when reranking is disabled or the pool is empty. A
+     * configured reranker that is unavailable, throws, or returns nothing for a
+     * non-empty pool throws, so the caller can report it and fall back.
      */
     private rerankPrefetchPool;
     /**
@@ -763,10 +786,17 @@ export declare class AutoRAGAgent {
      * not offer the tool.
      */
     private askUserException;
+    /**
+     * Fast-phase exception to the no-tools rule, naming only the web tools this
+     * session actually registered. Empty when web tools are off, so the prompt
+     * never mentions a tool the model does not have.
+     */
+    private fastPhaseWebHint;
     /**
      * Fast-phase prompt for two-phase searches. The baseline retrieval context
      * is already gathered, so the model answers immediately with minimal thinking,
-     * as plain text, without any further tool calls.
+     * as plain text, without further retrieval; the web tools are the only
+     * exception, for public facts the baseline cannot settle.
      */
     buildFastAnswerPrompt(query: string, options: RetrievalOptions, baseline: string): string;
     /**
@@ -776,35 +806,45 @@ export declare class AutoRAGAgent {
      */
     private isConversationTurn;
     /**
-     * Prompt for a question Jev routed to a direct answer: general knowledge or
-     * small talk. No retrieval ran and no verification phase follows, so the
-     * reply is the final answer.
+     * Prompt for a request Jev routed to `organize`: act on files and folders
+     * (move, rename, convert, sort). No route changes the active tools any more,
+     * so the prompt names the tools the task uses and the ones it must not, and
+     * carries the loaded organize skill with the rules. No retrieval ran and no
+     * verification follows; the model's plain final message is the answer.
      */
-    buildDirectAnswerPrompt(query: string): string;
+    buildOrganizePrompt(query: string, skill: PackagedAgentSkill): string;
     /**
-     * Tools an `organize` turn keeps: pi's file tools plus the converter, the
-     * duplicate scan, and file-name discovery, whichever this agent registered.
-     * The retrieval, datasource, and web tools stay out: the turn acts on files.
+     * The tool-scope sentence of an `organize` turn: the tools the task uses and
+     * the content-retrieval and web tools it must not call. Every route keeps the
+     * whole tool set now, so the prompt is what scopes the turn; both lists name
+     * only tools this agent actually registered, so the prompt never points the
+     * model at a tool the session does not have.
      */
-    private organizeToolNames;
+    private organizeToolScope;
     /**
-     * Prompt for a request Jev routed to `organize`: act on files and folders
-     * (move, rename, convert, sort). No retrieval ran and no verification
-     * follows; the model's plain final message is the answer.
+     * Prompt for a request Jev routed to `extra`: no branch had a confident
+     * non-local verdict, and handling it needs no search of the user's records
+     * first. Nothing was retrieved and nothing follows this turn — no fast
+     * answer, follow-up check, or verification — so the single tool-capable
+     * turn either answers the question or carries the task out. No tool is
+     * forbidden: the model looks facts up itself when they are not its own.
      */
-    buildOrganizePrompt(query: string): string;
+    buildExtraPrompt(query: string): string;
     /**
-     * Prompt for a request Jev routed to `extra`: a task that is neither
-     * knowledge, the user's records, file organization, nor configuration.
-     * The model acts with every tool it has; there is no retrieval or verification phase.
+     * One tool-capable turn for an action route (`organize`, `extra`): the model
+     * carries the request out with the tools it has and reports through its plain
+     * final message. No retrieval, no fast answer, no verification — and no route
+     * changes the session's active tools, so the turn prompt is what scopes the
+     * work. Returns the report, or `undefined` when the user stopped the run or
+     * the turn ended without one.
      */
-    buildExtraPrompt(query: string): string;
+    private runActionTurn;
     /** Discovery-tool hint naming only the registered discovery tools; empty when none. */
     private discoveryHint;
     /**
-     * Verification-phase nudge toward the internet. Jev no longer routes to web
-     * search, so the agent decides after the fast answer: when local evidence is
-     * missing, thin, or possibly stale, it searches the web. Empty when web tools are off.
+     * Verification-phase nudge toward the internet, for when the web was not
+     * selected before the fast answer or its evidence fell short: when local
+     * evidence is missing, thin, or possibly stale, the agent searches the web. Empty when web tools are off.
      */
     private webFallbackHint;
     /**

package/dist/agent/answer-guidelines.d.ts

@@ -31,13 +31,30 @@ export declare const ANSWER_EMPHASIS_RULE = "**Emphasis**: put the values a read
 export declare const ANSWER_LANGUAGE_RULE = "**Answer language**: write the answer in the language of the user's question (a Korean question gets a Korean answer) even when the sources are in another language; if the user asks for a specific language, use that one. Keep proper nouns, identifiers, code, and terms quoted from sources in their original form.";
 /** Uncertainty goes last so it never buries the conclusion. */
 export declare const ANSWER_UNCERTAINTY_RULE = "**Uncertainty placement**: when the answer is incomplete or uncertain, state that in one short sentence on the last line of the answer, never before or ahead of the conclusion. Do not hedge the conclusion itself.";
+/**
+ * Every sentence answers the question. Models that find nothing on point tend to
+ * prove the search was thorough by listing what they found instead and why it
+ * does not match; the caller never asked for that, so it is left out for every
+ * phase, delta included.
+ */
+export declare const ANSWER_RELEVANCE_RULE = "**Answer only what was asked**: every sentence must answer the user's question. Never list retrieved items, topics, documents, or figures that do not answer it, never describe how or where you searched, and never explain why something was left out or how it differs from what was asked (no \"I also found X, but it is not what you asked\", no near-miss lists, no \"nothing about Y, only Z\", no inventory of the sources that lacked it). Unrelated or merely adjacent material is omitted entirely unless the user asked for related items or alternatives.";
+/**
+ * Fast phase, no supporting evidence: park the question in one line. The
+ * verification phase that follows keeps searching, so the line is true.
+ */
+export declare const ANSWER_UNCONFIRMED_FAST_RULE = "**When the evidence does not answer the question yet**: do not build an answer out of what was found instead, and do not argue that the answer is absent by naming what the sources did contain (no \"only X exists\" contrast). The whole answer is then one short line saying it is not confirmed yet and that you are searching further (the verification phase that follows does the searching), with no bullets and no citations. A different subject, place, year, or party is unrelated evidence, not part of the answer. If a part the user actually asked for is answered, answer that part normally and say on the last line what is still being searched.";
+/**
+ * Phases that can end the run: search before giving up, and when the search
+ * still finds nothing the answer is one line, not an inventory of the corpus.
+ */
+export declare const ANSWER_UNCONFIRMED_FINAL_RULE = "**When the answer cannot be found**: keep searching first (different terms, synonyms, other retrieval methods or datasources) instead of answering from unrelated results. If it still cannot be confirmed, the whole answer is one short line saying so, with no bullets, no citations, no mention of what was found instead (no \"only X exists\" contrast), and no account of where you looked or what the documents do contain. A different subject, place, year, or party is unrelated evidence, not part of the answer. If a part the user actually asked for is answered, answer that part normally and say on the last line what is still unconfirmed.";
 /**
  * Inline evidence citations. The model writes the id the retrieval tools print
  * next to each result; the harness resolves it to the recorded source and
  * renumbers the markers `[1]`, `[2]`, ... (a source keeps its number for the whole
  * conversation), so the caller only ever sees numbered citations backed by recorded evidence.
  */
-export declare const ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else.";
+export declare const ANSWER_CITATION_RULE = "**Citations**: cite supporting evidence inline with the evidence id shown next to each retrieved result, in square brackets (e.g. [e3], or [e3][e7] for two). Copy ids exactly; never invent one. For a local file you opened yourself with `bash`, cite `[file:<absolute path>]`. Cite the evidence that backs a sentence at the end of that sentence. Do not cite numbers, paths, or anything else. A retrieved result may carry a measured location note such as `(lines 7-8, section \"\uC81C5\uC870(\uD68C\uC6D0\uC758 \uC758\uBB34)\")` next to its id: when you state a line number, line range, or article/section of a passage, copy it from that note, and when no note is printed give none. Never count or infer line numbers yourself, and never state how many items (paragraphs, articles, results) there are unless you counted them in the quoted text.";
 /**
  * Deliverable/artifact rule (issue #1832). The 5-bullet cap and direct-answer
  * format remain the default unless the user explicitly asks otherwise; when the

package/dist/agent/current-date.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The prompt block that tells the model what "now" is. AutoRAG replaces pi's whole
+ * system prompt, so nothing else gives the model a clock; without it "last month",
+ * "this year", "is the deadline past", and "the most recent" have no anchor.
+ *
+ * Built per turn from the host's local clock and time zone, so a session left open
+ * for days never shows yesterday's date. It sits last in the prompt so the stable
+ * part before it keeps its prompt-cache prefix.
+ */
+export declare function currentDateAddendum(now?: Date): string;

package/dist/agent/datasource-skill.d.ts

@@ -36,8 +36,8 @@ export declare function toDatasourceAgentSkill(manifest: DatasourceSkillManifest
  */
 export declare function buildDatasourceSkillsPrompt(skills: readonly DatasourceAgentSkill[]): string;
 /**
- * Format the full instructions for a loaded datasource skill, matching pi's
- * `<skill …>` invocation shape but with a path-opaque location (no real
+ * Format the full instructions for a loaded datasource skill in the shared
+ * `<skill …>` invocation shape, with a path-opaque location (no real
  * filesystem reference, so no "references are relative to …" line).
  */
 export declare function formatDatasourceSkillInvocation(skill: DatasourceAgentSkill): string;

package/dist/agent/environment-prompt.d.ts

@@ -0,0 +1,20 @@
+export interface EnvironmentInfo {
+    readonly cwd: string;
+    readonly platform: string;
+    readonly arch: string;
+    readonly release: string;
+    /** The shell the `bash` tool runs commands in; undefined when pi found none. */
+    readonly shell: string | undefined;
+}
+/**
+ * Where the agent runs: OS, shell, and working directory. AutoRAG replaces pi's whole
+ * system prompt, so without this the model writes POSIX commands for a Windows host
+ * and relative paths against an unknown directory. Fixed for the life of a session.
+ */
+export declare function environmentAddendum(info: EnvironmentInfo): string;
+/**
+ * Everything the host appends after AutoRAG's own prompt. Ordered most stable first:
+ * the environment never changes in a session, the date changes every minute, so the
+ * longest possible prefix of the prompt stays identical between turns for prompt caching.
+ */
+export declare function runtimeContextAddendum(cwd: string, now?: Date): string;

package/dist/agent/evidence-ledger.d.ts

@@ -8,11 +8,12 @@ export interface LedgerEvidenceInput {
     readonly retrievalResultId?: string;
     readonly chunkIndex?: number;
     readonly lineNumber?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
     readonly parserType?: string;
     readonly documentType?: string;
     readonly documentArea?: string;
     readonly evidenceType?: string;
-    readonly evidenceLocation?: string;
 }
 /** Custom session entry type under which a conversation persists its evidence ledger. */
 export declare const EVIDENCE_ENTRY_TYPE = "autorag.evidence";
@@ -27,11 +28,12 @@ declare const ledgerEntrySchema: Type.TObject<{
     retrievalResultId: Type.TOptional<Type.TString>;
     chunkIndex: Type.TOptional<Type.TNumber>;
     lineNumber: Type.TOptional<Type.TNumber>;
+    lineEnd: Type.TOptional<Type.TNumber>;
+    section: Type.TOptional<Type.TString>;
     parserType: Type.TOptional<Type.TString>;
     documentType: Type.TOptional<Type.TString>;
     documentArea: Type.TOptional<Type.TString>;
     evidenceType: Type.TOptional<Type.TString>;
-    evidenceLocation: Type.TOptional<Type.TString>;
 }>;
 /** One recorded piece of evidence: what a retrieval tool returned, under the id it printed. */
 export type LedgerEntry = Static<typeof ledgerEntrySchema>;

package/dist/agent/location-claims.d.ts

@@ -0,0 +1,14 @@
+/** A line range a cited chunk occupies in its parsed document. */
+export interface CitedLineRange {
+    readonly lineStart?: number;
+    readonly lineEnd?: number;
+}
+/**
+ * Line numbers `prose` states that no cited chunk covers, each once, in order of
+ * appearance. The line range of a chunk is measured from the parsed document,
+ * so a number outside every cited range is one the model made up or miscounted.
+ *
+ * Nothing can be checked when no cited chunk carries a line range, so that
+ * yields no claims rather than flagging every number.
+ */
+export declare function findUnverifiedLineClaims(prose: string, cited: readonly CitedLineRange[]): number[];

package/dist/agent/packaged-skill.d.ts

@@ -0,0 +1,19 @@
+import type { SkillInvocation } from "./skill-invocation.js";
+/** The packaged `autorag-setup` skill, loaded for the Jev `config` branch. */
+export declare const SETUP_SKILL_NAME = "autorag-setup";
+/** The packaged `organize` skill, loaded for the Jev `organize` branch. */
+export declare const ORGANIZE_SKILL_NAME = "organize";
+/** A packaged skill as a turn prompt needs it: name, opaque location, body. */
+export type PackagedAgentSkill = SkillInvocation;
+/**
+ * Opaque, path-free location used for a packaged agent skill. Packaged skills
+ * live on disk, but AutoRAG never exposes real filesystem paths to the model.
+ */
+export declare function packagedSkillLocation(name: string): string;
+/**
+ * Load one packaged agent skill: the file at `path` when given (the host's
+ * override), otherwise the packaged skill named `name`. The body is returned
+ * with its YAML front matter removed, so the model sees only instructions.
+ * Throws when the skill cannot be found or read; callers fall back to `local`.
+ */
+export declare function loadPackagedSkill(name: string, path?: string): PackagedAgentSkill;

package/dist/agent/query-routing.d.ts

@@ -2,21 +2,25 @@ import type { JevJudge } from "./jev-extension.js";
 /**
  * Where a user question is answered from:
  * - `local`: anything needing information beyond the model's own knowledge —
- *   the user's files, chats, mail, or any fact the model cannot reliably recall.
- *   Local retrieval runs first; web search is left to the agent after the fast
- *   answer, when local evidence falls short.
- * - `direct`: intrinsic knowledge or small talk the model answers on its own.
+ *   the user's files, chats, mail, or any fact the model cannot reliably recall,
+ *   recent, specific, or changing public facts included. Local retrieval runs
+ *   first, together with every datasource Jev selects, the public web among
+ *   them when web tools are enabled.
  * - `organize`: the user wants files or folders acted on — move, rename in
  *   bulk, rename by content, convert, sort, tidy — rather than information
  *   found. No retrieval and no verification: one tool-capable turn does it.
- * - `extra`: none of the other branches (committing code, opening a pull
- *   request, running a build, any other task for the agent's tools). The Jev
- *   gate is skipped: no retrieval, no verification, tools stay available.
+ * - `extra`: neither of the other branches, and no search of the user's own
+ *   records is needed first: the request is answerable from the model's own
+ *   knowledge (stable general knowledge, definitions, simple reasoning, small
+ *   talk), or it is a task for the agent's tools that is not file organization
+ *   and not AutoRAG configuration (commit, PR, build, write code, run a
+ *   script). No retrieval, decomposition, fast answer, follow-up check, or
+ *   verification: one tool-capable turn does it, with every tool available.
  * - `config`: the user wants to inspect or change AutoRAG's own settings
  *   (model, providers, datasources). Offered only when the host enables
  *   agent self-configuration.
  */
-export type QueryRoute = "local" | "direct" | "organize" | "extra" | "config";
+export type QueryRoute = "local" | "organize" | "extra" | "config";
 /** Jev question id of the intrinsic-knowledge / local branch. */
 export declare const QUERY_ROUTE_QUESTION_ID = "route";
 /** Jev question id of the "does this need decomposition?" check. */
@@ -29,10 +33,36 @@ export declare const FALLBACK_QUERY_ROUTE: QueryRoute;
 export declare const DECOMPOSE_PROBABILITY_THRESHOLD = 0.5;
 /** A `noul` probability at or above this sends the fast answer on to verification. */
 export declare const FOLLOW_UP_PROBABILITY_THRESHOLD = 0.5;
+/**
+ * Minimum Jev branch probability required to leave local search. A non-local
+ * branch (`organize`, `extra`, `config`) at or below this floor — or one Jev
+ * reported without a probability — keeps the run on local search, the
+ * corpus-grounded default, with a `query-route-fallback` diagnostic naming the
+ * floor as the reason (the rejected branch's probability is still reported as
+ * `routeProbability`). Without the floor a weakly-favored non-local verdict
+ * skips retrieval entirely, so a question that depends on the user's own
+ * records can be answered from general knowledge instead.
+ *
+ * The floor does not weaken a real non-local verdict: the fallback is a
+ * full local plan (datasource selection and decomposition still run). Removed
+ * by #1995 (982e464d) together with the intrinsic-knowledge branch, restored
+ * here because the reasons above did not go away.
+ */
+export declare const NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD = 0.75;
 /** A `noul` probability at or above this searches that datasource before the fast answer. */
 export declare const DATASOURCE_PROBABILITY_THRESHOLD = 0.5;
 /** Jev question id of the "search this datasource?" check for one datasource. */
 export declare function datasourceQuestionId(datasourceId: string): string;
+/**
+ * Reserved candidate id of the public web in the datasource gate.
+ *
+ * Datasource ids come from the config's `datasources` keys, which are only
+ * required to be non-empty (see `DatasourceSkillRegistry.register`), so a
+ * configured datasource *can* be called `web`. When one is, the web candidate
+ * is withheld and {@link DatasourceSelection.webIdTaken} says so, so the
+ * question id `datasource:web` always names exactly one candidate.
+ */
+export declare const WEB_DATASOURCE_ID = "web";
 export interface FollowUpDecision {
     /** True when the run continues into the verification phase. */
     readonly followUp: boolean;
@@ -49,27 +79,37 @@ export interface FollowUpDecision {
  */
 export declare function needsFollowUp(judge: JevJudge, query: string, answer: string): Promise<FollowUpDecision>;
 export interface QueryRouteDecision {
-    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none. */
+    /** Most probable branch; {@link FALLBACK_QUERY_ROUTE} when Jev gave none or its non-local branch missed {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}. */
     readonly route: QueryRoute;
-    /** True when Jev judged the question needs decomposition (only ever for `local`). */
+    /** True when Jev judged the question needs decomposition; only a `local` route acts on it. */
     readonly decompose: boolean;
-    /** Probability Jev gave the winning branch; absent when Jev reported none. */
+    /** Probability Jev gave the winning branch, including a rejected non-local branch whose floor moved the route to local. */
     readonly routeProbability?: number;
     /** Jev's P(decomposition needed), when it answered. */
     readonly decomposeProbability?: number;
     /** Why the decision fell back instead of following Jev; absent when Jev decided. */
     readonly fallbackReason?: string;
+    /**
+     * True when a non-local branch won but did not clear
+     * {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}: `route` is `local` and the
+     * full local plan still runs (datasource selection and decomposition),
+     * unlike a fallback from an unavailable or unusable verdict, which keeps a
+     * bare single-query local search.
+     */
+    readonly floorApplied?: boolean;
 }
 export interface RouteQueryOptions {
     /** Offer the `config` branch: the agent may change its own settings. */
     readonly selfConfig?: boolean;
 }
 /**
- * Ask Jev, in one batched call about the user question, which branch answers
- * it and whether it needs decomposition. The most probable branch wins, with
- * no confidence floor. Never throws: a missing credential, an unreachable
- * backend, or an unusable verdict falls back to a single local search, with
- * the reason recorded.
+ * Ask Jev, in one batched call about the user question, which branch handles it
+ * and whether it needs decomposition. The most probable branch wins once it
+ * clears {@link NON_LOCAL_ROUTE_PROBABILITY_THRESHOLD}: a weakly-favored or
+ * probability-less `organize`, `extra`, or `config` verdict keeps the local
+ * default and still runs the full local plan (`floorApplied`). Never throws: a
+ * missing credential, an unreachable backend, or an unusable verdict falls back
+ * to a single local search, with the reason recorded.
  */
 export declare function routeQuery(judge: JevJudge, query: string, options?: RouteQueryOptions): Promise<QueryRouteDecision>;
 /** One configured datasource Jev may send the question to. */
@@ -81,12 +121,23 @@ export interface DatasourceCandidate {
     readonly description: string;
 }
 export interface DatasourceSelection {
-    /** Datasource ids to search, in registration order. */
+    /** Datasource ids to search, in registration order; the web candidate's id is {@link WEB_DATASOURCE_ID}. */
     readonly selected: readonly string[];
-    /** Jev's P(search needed) per datasource id, for every datasource it answered. */
+    /** Jev's P(search needed) per candidate id, for every candidate it answered. */
     readonly probabilities: Readonly<Record<string, number>>;
     /** Why no datasource is searched instead of following Jev; absent when Jev decided. */
     readonly fallbackReason?: string;
+    /**
+     * True when the web candidate was withheld because a configured datasource
+     * already uses {@link WEB_DATASOURCE_ID}: `datasource:web` then names that
+     * configured datasource, and the run searches no web before the fast answer.
+     */
+    readonly webIdTaken?: boolean;
+}
+/** Options of {@link selectDatasources}. */
+export interface SelectDatasourcesOptions {
+    /** Offer the public web as one more candidate (the host has web tools enabled). */
+    readonly web?: boolean;
 }
 /** A similar question asked before, its results, and where each was found. */
 export interface PastSearchHint {
@@ -101,12 +152,15 @@ export interface PastSearchHint {
     }[];
 }
 /**
- * Ask Jev, in one batched call, one `noul` per registered datasource: does
- * answering the question need that datasource searched? The state describes
- * every datasource (descriptions are flagged as non-exhaustive summaries), so
- * Jev judges each one against the others, plus where similar past questions
- * were answered, when retrieval memory has any. Never throws: a missing
- * credential or an unreachable backend searches no datasource, which is the
- * behavior without Jev.
+ * Ask Jev, in one batched call, one `noul` per candidate: does answering the
+ * question need that datasource searched? The state describes every candidate
+ * (descriptions are flagged as non-exhaustive summaries), so Jev judges each
+ * one against the others, plus where similar past questions were answered,
+ * when retrieval memory has any. With `options.web`, the public web is one
+ * more candidate, under the reserved id {@link WEB_DATASOURCE_ID}; it is
+ * withheld when a configured datasource already uses that id
+ * ({@link DatasourceSelection.webIdTaken}), so a question id never names two
+ * candidates. Never throws: a missing credential or an unreachable backend
+ * searches nothing, which is the behavior without Jev.
  */
-export declare function selectDatasources(judge: JevJudge, query: string, datasources: readonly DatasourceCandidate[], pastSearches?: readonly PastSearchHint[]): Promise<DatasourceSelection>;
+export declare function selectDatasources(judge: JevJudge, query: string, datasources: readonly DatasourceCandidate[], pastSearches?: readonly PastSearchHint[], options?: SelectDatasourcesOptions): Promise<DatasourceSelection>;

package/dist/agent/results.d.ts

@@ -16,6 +16,8 @@ export declare const reportSchema: Type.TObject<{
         evidence: Type.TArray<Type.TObject<{
             excerpt: Type.TString;
             lineNumber: Type.TOptional<Type.TInteger>;
+            lineEnd: Type.TOptional<Type.TInteger>;
+            section: Type.TOptional<Type.TString>;
         }>>;
         confidence: Type.TNumber;
     }>>;
@@ -38,7 +40,8 @@ export declare const reportSchema: Type.TObject<{
             documentType: Type.TOptional<Type.TString>;
             documentArea: Type.TOptional<Type.TString>;
             evidenceType: Type.TOptional<Type.TString>;
-            evidenceLocation: Type.TOptional<Type.TString>;
+            lineEnd: Type.TOptional<Type.TInteger>;
+            section: Type.TOptional<Type.TString>;
             confidence: Type.TOptional<Type.TNumber>;
         }>>>;
     }>>;
@@ -47,6 +50,10 @@ export declare const reportSchema: Type.TObject<{
 export interface AutoRAGEmittedEvidence {
     readonly excerpt: string;
     readonly lineNumber?: number;
+    /** Last line of the chunk; with {@link lineNumber} the exact range in the parsed document. */
+    readonly lineEnd?: number;
+    /** Article or heading the chunk sits in. */
+    readonly section?: string;
 }
 export interface AutoRAGEmittedResult {
     readonly number: number;
@@ -64,13 +71,14 @@ export interface AutoRAGEvidenceRef {
     readonly retrievalResultId?: string;
     readonly chunkIndex?: number;
     readonly lineNumber?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
     readonly stableEvidenceId?: string;
     readonly retrieverMix?: readonly string[];
     readonly parserType?: string;
     readonly documentType?: string;
     readonly documentArea?: string;
     readonly evidenceType?: string;
-    readonly evidenceLocation?: string;
     readonly confidence?: number;
 }
 export interface AutoRAGMappingEntry {