@autorag/librarian 2.10.6 → 2.11.0

package/NOTICE

@@ -77,3 +77,11 @@ licenses/everything-MIT-and-PCRE-BSD.txt
 ES 1.1.0.38 command-line interface (voidtools)
 License: MIT
 licenses/es-MIT.txt
+
+Separate programs AutoRAG talks to (not bundled, not distributed, not linked):
+Hister (https://github.com/asciimoo/hister, asciimoo and Hister contributors)
+License: AGPL-3.0-or-later
+AutoRAG ships no Hister code. Users install the unmodified Hister release themselves and AutoRAG only sends
+search requests to its public HTTP API (GET /search, GET /api/config), as a separate program over a network
+socket. AutoRAG does not modify Hister and never hides that Hister is the backend of the `hister` datasource.
+licenses/hister-AGPL-3.0-notice.txt

package/README.md

@@ -18,7 +18,7 @@
 
 > [!IMPORTANT]
 > **Looking for the original AutoRAG (RAG AutoML / pipeline optimization tool)?**
-> This repository now hosts **AutoRAG 2.0**, a complete reimagining of AutoRAG as a self-evolving librarian agent. The original Python-based AutoRAG — the RAG AutoML tool for automatically finding an optimal RAG pipeline for your data — now lives in the [`legacy/`](legacy/) directory of this repository.
+> This repository now hosts **AutoRAG 2.0**, a complete reimagining of AutoRAG as a personal librarian agent for your office work. The original Python-based AutoRAG — the RAG AutoML tool for automatically finding an optimal RAG pipeline for your data — now lives in the [`legacy/`](legacy/) directory of this repository.
 >
 > **The legacy AutoRAG is NOT abandoned.** It continues to be maintained (bug fixes, dependency updates, and PyPI releases via `pip install AutoRAG`) in maintenance mode. Existing users can keep using it exactly as before — see the [legacy README](legacy/README.md) for its documentation, and file issues in this repository as usual. New feature development is focused on AutoRAG Agent (2.0).
 
@@ -166,7 +166,7 @@ The app is one way in. The same librarian runs everywhere else:
 
 Search tools dump file paths and matching lines — forcing you to open files, read context, and synthesize answers yourself.
 
-**AutoRAG Agent is a self-evolving librarian agent.** Built on the [Pi](https://github.com/earendil-works/pi-mono) agent framework, a single configured model searches across multiple retrieval methods, opens source documents directly via `bash` to verify ground truth, and curates answers into clean, numbered knowledge units:
+**AutoRAG Agent is a personal librarian agent that helps with your office work.** Built on the [Pi](https://github.com/earendil-works/pi-mono) agent framework, a single configured model searches your files, mail, chats, and notes in place, opens source documents directly via `bash` to verify ground truth, and curates answers into clean, numbered knowledge units. Because it works for you rather than only on your index, it can also act on your files when you ask, such as organizing, renaming, moving, or editing them with a record of every change:
 
 ```text
 You ask:  "What changes were made to the cloud infrastructure contract in Q3?"
@@ -187,7 +187,7 @@ AutoRAG Agent:
 
 Three principles drive every design decision in AutoRAG Agent:
 
-1. **Never migrate your data to search it.** Traditional RAG systems force you to upload, ETL, and duplicate your files into a centralized vector database. AutoRAG Agent federates your data **in place**, querying CLI-native stores (`lazykatok`, `discrawl`, `slacrawl`, `mailcrawl`, `rclone`, `qmd`) where your data already lives. Results retain opaque, source-native identities (`/kakao/...`, `/slack/...`) that preserve local access control and privacy. *(See our [Competitive Landscape Study](docs/competitive-landscape-2026-09.md) on why in-place federation is the durable differentiator).*
+1. **Never migrate your data to search it.** Traditional RAG systems force you to upload, ETL, and duplicate your files into a centralized vector database. AutoRAG Agent federates your data **in place**, querying CLI-native stores (`lazykatok`, `discrawl`, `slacrawl`, `mailcrawl`, `rclone`) where your data already lives. Results retain opaque, source-native identities (`/kakao/...`, `/slack/...`) that preserve local access control and privacy. *(See our [Competitive Landscape Study](docs/competitive-landscape-2026-09.md) on why in-place federation is the durable differentiator).*
 
 2. **Just works — no RAG degree required.** No pipeline tuning, no vector-DB maintenance, and no remote embedding keys required. AutoRAG Agent automatically manages [MinSync](docs/minsync-setup.md) for incremental Change Data Capture (CDC) chunking and provides a local [embedding backend](docs/minsync-setup.md#embedding-backends) out of the box with zero external telemetry. A [remote rerank model](docs/rerank.md) (the hosted Dazzi Models reranker when signed in, else OpenRouter `voyageai/rerank-3-lite`) is an opt-in extra.
 
@@ -218,8 +218,12 @@ AutoRAG uses `@earendil-works/pi-coding-agent` as the runtime host for model ses
 
 The CLI TUI (`autorag tui`) is Pi's interactive mode hosted on the AutoRAG librarian: there is no separate AutoRAG renderer. Pi owns the terminal UI and its native in-session commands — `/login`/`/logout`, `/model`, `/resume`, `/new`, `/tree`, `/compact`, and `/settings` — so provider sign-in and model selection work on first launch even when no AutoRAG model is configured. AutoRAG registers its retrieval tools and runs the two-phase search in the same Pi session, where the model's progress notes, first answer, and final answer are ordinary assistant messages, so resume and two-phase search keep working together.
 
+A fresh session — at launch and after `/new` (or `/reload`) — opens on AutoRAG's own welcome screen: the AutoRAG logo, the version, and three rotating tips, centered and scaled down to a smaller logo or a plain wordmark on narrow terminals. Pi's own logo, key-hint list, and loaded skills/prompts/extensions listing are hidden by default (`quietStartup: "header"`). A `quietStartup` saved in Pi's global or project `settings.json` wins: `true` removes the banner, `false` brings Pi's resource listing back.
+
 Typing while a search runs works like steering one of Pi's own turns. **Enter** steers the running search: AutoRAG treats the text as a correction of a search that is going wrong, delivers it before the search's next model request (also between phases, where no turn is streaming), cuts in-flight retrieval short so the correction lands promptly, and always runs the verification phase so the answer reflects the correction. **Alt+Enter** queues a new question that runs after the current search answers. **Esc** stops the search instead of letting it continue into its next phase. Pi's registered `/` commands still run during a search; any other line starting with `/` (a path, for example) is a steer like any other text. A query typed after a search answers is a new search in the same session, as before.
 
+From the moment a question is submitted, a live progress widget sits above the editor: a spinner, the elapsed time, and one line per step the search is running (routing, splitting the question, each retrieval source with its hit count and time, ranking, the first answer, verification). A slow source shows its own running timer, a failing source shows its error text verbatim, and the widget disappears when the answer is final or **Esc** stops the search. While the model streams, Pi's own `Working` loader takes over and the widget keeps only the header and steps.
+
 Update notices are AutoRAG's, not Pi's: `autorag tui` suppresses Pi's "run `pi update`" banner (Pi is a bundled host, not a separate install) and instead checks the published `@autorag/librarian` release, showing a one-line notice in the session when a newer version exists. Set `AUTORAG_NO_UPDATE_CHECK=1` to skip the lookup; `AUTORAG_UPDATE_CHECK_URL` overrides the registry endpoint.
 
 ---
@@ -501,6 +505,36 @@ Core Lite tools include `autorag.status`, `autorag.search`,
 integrated datasources expose additional scoped search tools. Read-only MCP
 mode omits mutating tools such as refresh and report.
 
+## Using external MCP servers and agent skills
+
+AutoRAG is also an MCP *client*. Servers listed in the pi agent directory's `mcp.json`
+(`~/.pi/agent/mcp.json`, or `<piAgentDir>/mcp.json` when the agent is given one) are connected
+when a TUI session or a one-shot `autorag search` starts, and their tools reach the model next to
+AutoRAG's own tools. The file uses the format shared by other MCP clients:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
+    "docs": { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" } }
+  }
+}
+```
+
+- **Exposure.** By default a server's tools are reached through the `codemode` tool (the model
+  writes a short script that calls them); `"exposure": "direct"` declares them to the model
+  like built-in tools, `"deferred"` loads them on demand through `tool_search`, and `"hidden"`
+  turns a server off. `description` is shown to the model so it knows when to use the server.
+- **Only the user-level file is read.** A project `.pi/mcp.json` is ignored on purpose: it would
+  let any folder AutoRAG starts in choose which processes run.
+- **Failures are reported verbatim.** An invalid entry or a server that fails to start is
+  reported at session start with pi's own message; the other servers keep working.
+- **Inside the TUI**, `/mcp` lists servers, reconnects them, signs in to OAuth servers, and
+  changes exposure. Pi's `/skill:<name>` commands and `<available_skills>` list also work for
+  any agent skill installed under the agent directory.
+- MCP results are data from an external server. AutoRAG tells the model never to follow
+  instructions found in them.
+
 ---
 
 ## ⚡ AutoRAG Lite: Model-Free Retrieval Engine
@@ -584,7 +618,8 @@ Do not copy or retain the removed `autorag-lite-search` skill.
    autorag search "your question" --json
    ```
 4. **Safety Guidelines for Agents:**
-   - **Never delete, move, or modify original user documents.**
+   - **Setup, diagnostics, indexing, and refresh never modify your documents.** An agent that installs, configures, or repairs AutoRAG (Claude Code, Codex, and similar) must not move, rename, edit, or delete user documents as part of that work. That rule is about those procedures; it is not a limit on the librarian itself, which may organize, create, or modify files in local sessions when the user asks (see `Local File Organization` in the system prompt).
+   - **Never permanently delete.** Deletion goes to the OS trash, and every change is listed as old path → new path so it can be undone.
    - AutoRAG writes index artifacts into `<workspace>/.autorag/` and Jikji's central store (`<OS data dir>/jikji/`, override with `JIKJI_DATA_DIR`). Jikji also drops a `.jikji_agent_map.md` guide into each indexed root.
    - Never print or leak API keys, tokens, or credential values into stdout or logs.
 
@@ -605,13 +640,14 @@ AutoRAG Agent connects to external tools and communication platforms using dedic
 | **Notion** | `notion` | [`notcrawl`](https://github.com/openclaw/notcrawl) CLI | Local page/database/block archive + FTS5 | Lexical FTS5 |
 | **Email Archives** | `mailcrawl` | [`mailcrawl`](https://github.com/NomaDamas/mailcrawl) CLI | Local Gmail, IMAP, and Maildir storage | BM25, Semantic, Hybrid |
 | **Local Mail Export**| `mail-export` | Built-in `.mbox` / `.eml` parser | Local filesystem mailboxes | Lexical |
-| **Obsidian Vaults** | `obsidian` | [`qmd`](https://github.com/tobi/qmd) CLI | Direct markdown vault indexing | BM25, Semantic |
+| **Obsidian Vaults** | `obsidian` | Indexed with MinSync in its own workspace (no external CLI) | Markdown notes, folder-scopable | Lexical (BM25), Semantic, Scoped |
 | **GitHub** | `github` | GitHub REST API | In-memory fetched Issues and Pull Requests | Lexical, Scoped |
 | **GitHub Gists** | `github-gist` | GitHub REST API | Incremental local index of own-account public and permitted secret Gist content/metadata; token not stored | Lexical (BM25), Local Semantic, Scoped |
 | **Cloud Drives** | `cloud-drive` | [`rclone`](https://rclone.org) CLI | Google Drive (Tier-1), OneDrive, Dropbox, etc. | Incremental Mirror + BM25 |
 | **Photos & Shots** | `clawgallery` | `clawgallery` CLI | Local screenshot and photo store | Hybrid OCR/Visual Search |
 | **RSS / News** | `rss` | Native HTTP Poller | RSS 2.0 & Atom feeds (24h deduplication) | Lexical |
 | **macOS Spotlight** | `spotlight` | Native `mdfind` CLI | macOS system metadata and content index | System Native |
+| **Browser History** | `hister` | [Hister](https://github.com/asciimoo/hister) server (AGPL-3.0-or-later, separate program, HTTP API) | Pages visited in Chrome/Chromium/Firefox, captured by Hister's own extension and indexed by Hister (web pages only; its local-file indexing is never used) | Lexical full-text; optional Semantic via Hister's own embedding endpoint |
 
 For configuration syntax and connector details, see [docs/datasource-skills.md](docs/datasource-skills.md). Non-interactive `sync`/`index` steps get a 30-minute per-connector budget (`connector.indexTimeoutMs`) because first-run imports routinely take minutes; interactive search keeps its 60-second default.
 
@@ -692,6 +728,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 - **[Discord Remote Control](docs/discord.md):** Ask the librarian from a Discord channel through a running `autorag tui --discord` session: bot setup, permissions, and limits.
 - **[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) or local search (everything needing more information; web search is left to the agent after the fast answer), 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.
@@ -719,8 +756,9 @@ AutoRAG Agent stands on the shoulders of fantastic open-source projects:
 - **[Jikji](https://github.com/NomaDamas/jikji)** by [NomaDamas](https://github.com/NomaDamas) — High-performance find-first local document discovery.
 - **[Everything](https://www.voidtools.com/)** and **[ES](https://github.com/voidtools/ES)** by voidtools (David Carpenter) — Instant Windows file-name indexing and its command-line interface, bundled under the MIT License.
 - **[FSearch](https://github.com/cboxdoerfer/fsearch)** and **[fsearch-cli](https://github.com/NomaDamas/fsearch-mac)** — Everything-style file-name search for macOS/Linux (GPL-2.0-or-later). Never bundled or linked: users install fsearch-cli separately and AutoRAG spawns it as a separate process (mere aggregation per the FSF GPL FAQ).
+- **[Hister](https://github.com/asciimoo/hister)** by [asciimoo](https://github.com/asciimoo) and contributors — Self-hosted browser web-history search (AGPL-3.0-or-later). Never bundled, linked, copied, or modified: users run Hister as a separate program and AutoRAG only calls its public HTTP search API (mere aggregation). Hister is always named as the backend of the `hister` datasource.
 - **[dupey](https://github.com/NomaDamas/dupey)** by [NomaDamas](https://github.com/NomaDamas) — Fast duplicate and near-duplicate document family detection.
-- **Federated CLI Authors:** External datasource tools [`lazykatok`](https://github.com/changeroa/lazykatok), [`discrawl`](https://github.com/openclaw/discrawl), [`mailcrawl`](https://github.com/NomaDamas/mailcrawl), [`wacrawl`](https://github.com/openclaw/wacrawl), [`telecrawl`](https://github.com/openclaw/telecrawl), [`slacrawl`](https://github.com/openclaw/slacrawl), [`notcrawl`](https://github.com/openclaw/notcrawl), [`qmd`](https://github.com/tobi/qmd), and [`rclone`](https://rclone.org).
+- **Federated CLI Authors:** External datasource tools [`lazykatok`](https://github.com/changeroa/lazykatok), [`discrawl`](https://github.com/openclaw/discrawl), [`mailcrawl`](https://github.com/NomaDamas/mailcrawl), [`wacrawl`](https://github.com/openclaw/wacrawl), [`telecrawl`](https://github.com/openclaw/telecrawl), [`slacrawl`](https://github.com/openclaw/slacrawl), [`notcrawl`](https://github.com/openclaw/notcrawl), and [`rclone`](https://rclone.org).
 - **[kordoc](https://github.com/chrisryugj/kordoc)** by [chrisryugj](https://github.com/chrisryugj) — HWP/HWPX/HWPML, PDF, DOCX and XLSX parsing with nested-table fidelity, used as AutoRAG's default document parser.
 
 ---
@@ -765,7 +803,7 @@ Common failures and their fix:
 | Windows file-name search fails during refresh | `everything-index-failed` | read the ES exit code and stderr in the message, then `autorag refresh --method everything --json` |
 | Every search does a full local search and verification, even for small talk | `query-route-fallback` | sign in to Dazzi Models with `/login`, or set `OPENROUTER_API_KEY` (Jev routing and decomposition are on by default) |
 
-Native datasource stores stay owned by their CLIs — AutoRAG never rebuilds them. Fix a broken archive with `lazykatok doctor`, `discrawl --json metadata`, `slacrawl --json doctor`, `wacrawl --json doctor`, `telecrawl --json doctor`, `notcrawl doctor`, `qmd status`, or `mailcrawl doctor`, then re-run `autorag refresh --method datasources --json`.
+Native datasource stores stay owned by their CLIs — AutoRAG never rebuilds them. Fix a broken archive with `lazykatok doctor`, `discrawl --json metadata`, `slacrawl --json doctor`, `wacrawl --json doctor`, `telecrawl --json doctor`, `notcrawl doctor`, or `mailcrawl doctor`, then re-run `autorag refresh --method datasources --json`.
 
 ---
 
@@ -776,3 +814,4 @@ Native datasource stores stay owned by their CLIs — AutoRAG never rebuilds the
 - Production third-party notices and licenses are documented in [`NOTICE`](NOTICE).
 - The bundled Windows binaries keep their own licenses: Everything (MIT, plus PCRE BSD-3-Clause) in [`licenses/everything-MIT-and-PCRE-BSD.txt`](licenses/everything-MIT-and-PCRE-BSD.txt) and ES (MIT) in [`licenses/es-MIT.txt`](licenses/es-MIT.txt). Everything's source code is not public; AutoRAG redistributes the unmodified voidtools portable ZIPs.
 - FSearch/fsearch-cli (GPL-2.0-or-later) are **not** distributed with AutoRAG: no code is copied, linked, or bundled. Users install fsearch-cli themselves and AutoRAG communicates with it only through its command-line interface and daemon socket — separate programs, per the [FSF mere-aggregation FAQ](https://www.gnu.org/licenses/gpl-faq.html#MereAggregation). Source: https://github.com/NomaDamas/fsearch-mac.
+- Hister (AGPL-3.0-or-later) is **not** distributed with AutoRAG: no Hister code is copied, linked, bundled, or modified. Users install an unmodified Hister release themselves and AutoRAG talks to that separate process only over its public HTTP API. Notice: [`licenses/hister-AGPL-3.0-notice.txt`](licenses/hister-AGPL-3.0-notice.txt). If you run Hister as a service for other people, AGPL section 13 applies to you as its operator.

package/dist/agent/agent.d.ts

@@ -345,6 +345,8 @@ export interface AutoRAGAgentOptions {
      * a launch.
      */
     updateNotice?: () => Promise<string | undefined>;
+    /** Interactive only: show the AutoRAG welcome banner (with this version) instead of pi's startup header. */
+    welcomeVersion?: string;
     /** Extension entry files (installed pi packages) loaded into the interactive session. */
     piExtensionPaths?: readonly string[];
     /** Flag values for the flags those extensions register. */
@@ -379,7 +381,7 @@ export interface AutoRAGSearchSession {
     readonly piSession?: AutoRAGPiSession["session"];
     prompt(text: string): Promise<void>;
     abort(): Promise<void> | void;
-    dispose(): void;
+    dispose(): void | Promise<void>;
 }
 export type AutoRAGJikjiPrepareResult = {
     readonly ok: true;
@@ -414,6 +416,8 @@ export declare class AutoRAGAgent {
      * state for `searchDocuments()` / `searchDocumentsStream()` callers.
      */
     private readonly interactive;
+    /** What the running search is doing, shown as a live widget in the TUI. */
+    private readonly searchProgress;
     /** Aborted by {@link abort} and by the run's timeout: gates publishing and the run's own requests. */
     private activeRunAbort;
     private modelNativeSearchAuth;
@@ -475,6 +479,7 @@ export declare class AutoRAGAgent {
     private readonly piSessionDir;
     private readonly persistPiSessions;
     private readonly updateNotice;
+    private readonly welcomeVersion;
     private readonly piExtensionPaths;
     private readonly piExtensionFlags;
     private readonly telegram;

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

@@ -10,6 +10,27 @@ export declare const ANSWER_IMAGE_EMBED_RULE = "**Images**: when a retrieved res
  * already showed.
  */
 export declare const ANSWER_IMAGE_DELTA_RULE = "An image already embedded in the first answer must not be embedded again.";
+/**
+ * Answer readability rules. Every surface that tells the model how to write the
+ * answer (system prompt, fast/complete/delta/search phase prompts, report
+ * schema) carries the same wording, so the answer's shape does not depend on
+ * which phase produced it. Each rule yields to an explicit user request for a
+ * different format.
+ */
+/**
+ * Conclusion first. Only complete answers get a lead line: a delta answer holds
+ * only corrections and new findings, and a lead conclusion would restate the
+ * first answer. The lead is outside the 5-bullet cap so the cap stays intact.
+ */
+export declare const ANSWER_LEAD_RULE = "**Lead with the conclusion**: unless the user explicitly requests a different format, start the answer with one line that states the conclusion in **bold**, followed by the supporting bullet points. The lead line is not counted in the 5-bullet cap. When the whole answer is a single fact, the lead line alone is enough and no bullets are needed.";
+/** One claim per bullet; flat list. */
+export declare const ANSWER_BULLET_RULE = "**One claim per bullet**: each bullet makes one claim in one or two sentences. Never nest bullets; split a bullet that carries two claims into two bullets.";
+/** Bold the values a reader scans for; tabulate real comparisons. */
+export declare const ANSWER_EMPHASIS_RULE = "**Emphasis**: put the values a reader scans for (dates, amounts, names, statuses, deadlines) in **bold**, and nothing else. When comparing three or more items across the same attributes, use a markdown table instead of bullets.";
+/** Answer language follows the question, not the sources. */
+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.";
 /**
  * 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
@@ -27,7 +48,7 @@ export declare const ANSWER_CITATION_RULE = "**Citations**: cite supporting evid
  * concise by stating the created file's location and briefly summarizing what
  * was generated (citing only the underlying source evidence).
  */
-export declare const ANSWER_DELIVERABLE_RULE = "**Deliverables and artifacts**: if the user asks you to draft, write, generate, or prepare a deliverable or artifact (a reply email, letter, legal opinion, summary document, standard-format case citation block, checklist, report, or workflow document \u2014 including requests phrased as \"how should I reply...\" to a specific message), produce the finished, ready-to-use artifact as a file (using `write`, `edit`, or `bash` in local sessions, without overwriting existing source files) in a file format, extension, and structure aligned with the context and domain (e.g. `.eml` or `.md`/`.txt` with headers for an email reply; `.md`, `.txt`, `.docx`, `.hwp`, or `.pdf` matching workspace conventions for a legal opinion, insertable case-citation block, or summary document; `.csv`, `.xlsx`, or `.json` for structured tabular data), containing the complete unabridged artifact (including required headers, precedent passages, pinpoint paragraphs, and standard-format citations) inside the file instead of merely describing how to produce it. Do NOT dump the full artifact text into your reply: unless the user explicitly requests otherwise, keep your reply concise within the at-most-5-bullet direct-answer format, clearly stating the created file's exact path/location and briefly summarizing what was generated with inline citations to the underlying source evidence (`[eN]` or `[file:<source path>]`); never cite the newly created deliverable file itself as `[file:...]`.";
+export declare const ANSWER_DELIVERABLE_RULE = "**Deliverables and artifacts**: if the user asks you to draft, write, generate, or prepare a deliverable or artifact (a reply email, letter, legal opinion, summary document, standard-format case citation block, checklist, report, or workflow document \u2014 including requests phrased as \"how should I reply...\" to a specific message), produce the finished, ready-to-use artifact as a file (using `write`, `edit`, or `bash` in local sessions) in a file format, extension, and structure aligned with the context and domain (e.g. `.eml` or `.md`/`.txt` with headers for an email reply; `.md`, `.txt`, `.docx`, `.hwp`, or `.pdf` matching workspace conventions for a legal opinion, insertable case-citation block, or summary document; `.csv`, `.xlsx`, or `.json` for structured tabular data), containing the complete unabridged artifact (including required headers, precedent passages, pinpoint paragraphs, and standard-format citations) inside the file instead of merely describing how to produce it. Do NOT dump the full artifact text into your reply: unless the user explicitly requests otherwise, keep your reply concise within the at-most-5-bullet direct-answer format, clearly stating the created file's exact path/location and briefly summarizing what was generated with inline citations to the underlying source evidence (`[eN]` or `[file:<source path>]`); never cite the newly created deliverable file itself as `[file:...]`.";
 /**
  * Verification-phase deliverable rule: create the context-aligned deliverable
  * file (in local sessions) and report its location and concise summary if the

package/dist/agent/mcp-client.d.ts

@@ -0,0 +1,27 @@
+import { type ExtensionFactory } from "@earendil-works/pi-coding-agent";
+/** pi's system-prompt section naming the MCP servers whose tools the model does not see declared. */
+export declare const MCP_SERVERS_SECTION = "mcp_servers";
+/**
+ * Tools pi's MCP integration owns. pi's `tools` allow-list keeps only named tools active, so every
+ * one of them has to be named: `mcp__*` covers each server tool, the rest are the codemode and
+ * tool-search entry points and the resource readers.
+ */
+export declare const MCP_TOOL_NAMES: string[];
+export interface AutoRAGMcpClient {
+    /** Extensions that connect the servers; the host registers them next to its own. */
+    readonly extensionFactories: readonly ExtensionFactory[];
+    /** Entries the session's `tools` allow-list needs so the extensions' tools stay active. */
+    readonly toolNames: readonly string[];
+}
+/**
+ * Connects the user's external MCP servers to an AutoRAG pi session, or returns `undefined` when
+ * `<agentDir>/mcp.json` is absent or names no enabled server, leaving the tool surface unchanged.
+ *
+ * Only the user-level file is read. pi would also load a project `.pi/mcp.json`, but that lets any
+ * directory AutoRAG starts in choose which processes run, so it is ignored by design. Entries go
+ * through `pi.registerMcpServer`, which validates them with pi's own rules; a rejected entry or an
+ * unreadable file is reported verbatim at session start and never stops the other servers.
+ */
+export declare function createAutoRAGMcpClient(agentDir: string): AutoRAGMcpClient | undefined;
+/** The prompt block for the servers pi reported in `sections`, or "" when it reported none. */
+export declare function mcpPromptAddendum(sections: Readonly<Record<string, string>> | undefined): string;

package/dist/agent/pi-session.d.ts

@@ -81,11 +81,19 @@ export interface AutoRAGPiInteractiveRuntimeOptions extends Omit<AutoRAGPiSessio
      * launch.
      */
     readonly updateNotice?: () => Promise<string | undefined>;
+    /**
+     * AutoRAG version shown on the welcome banner. Set only by the TUI: when present,
+     * every session start (launch, `/new`, `/resume`, `/reload`) replaces pi's startup
+     * header with the AutoRAG banner and hides pi's loaded-resource listing.
+     */
+    readonly welcomeVersion?: string;
 }
 export interface AutoRAGPiSession {
     readonly session: AgentSession;
     readonly baseToolNames: readonly string[];
     readonly sessionFile: string | undefined;
+    /** Stops what extensions started (MCP server processes), then disposes the session. */
+    readonly dispose: () => Promise<void>;
 }
 /** Adapts a pi-agent-core {@link AgentTool} to pi's extension {@link ToolDefinition}. */
 export declare function toToolDefinition(tool: AgentTool): ToolDefinition;

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

@@ -0,0 +1,96 @@
+import type { ExtensionFactory, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+/** Where pi shows the progress widget: its own slot above the editor, where the submitted question lands. */
+export declare const SEARCH_PROGRESS_WIDGET_KEY = "autorag-search-progress";
+export type SearchProgressStatus = "running" | "done" | "failed";
+/** One unit of work the search is doing (routing, one retrieval source, a model phase, …). */
+export interface SearchProgressStep {
+    readonly id: string;
+    readonly label: string;
+    readonly status: SearchProgressStatus;
+    /** Outcome text: the result count, the route, or the failure's own message. */
+    readonly detail?: string;
+    readonly startedAt: number;
+    readonly endedAt?: number;
+}
+/** An immutable view of the running search, handed to subscribers on every change. */
+export interface SearchProgressSnapshot {
+    readonly active: boolean;
+    readonly query: string;
+    readonly startedAt: number;
+    /** A model turn streams: pi's own working loader is on screen then. */
+    readonly modelStreaming: boolean;
+    readonly steps: readonly SearchProgressStep[];
+}
+/** Options of {@link SearchProgressTracker.track}. */
+export interface TrackOptions<T> {
+    /** How many hits a settled job returned; the step reports the sum. */
+    readonly count?: (value: T) => number;
+}
+/**
+ * What the running search is doing right now, in the user's terms. The agent
+ * reports into it; the TUI renders it so a silent first retrieval is visibly
+ * alive. Reports outside a begun search are ignored, so the library path
+ * (`searchDocuments()` with no UI) pays nothing.
+ */
+export declare class SearchProgressTracker {
+    private active;
+    private query;
+    private startedAt;
+    private modelStreaming;
+    /** Bumped by every {@link begin}: a job that settles after its search ended must not touch the next one. */
+    private run;
+    private steps;
+    private readonly listeners;
+    private readonly now;
+    constructor(now?: () => number);
+    begin(query: string): void;
+    end(): void;
+    setModelStreaming(streaming: boolean): void;
+    /** Starts (or restarts) a step that the caller closes with {@link endStep}. */
+    beginStep(id: string, label: string): void;
+    endStep(id: string, status: Exclude<SearchProgressStatus, "running">, detail?: string): void;
+    /**
+     * Runs `work` as step `id`: running while it is in flight, done with
+     * `detail(value)` when it resolves, failed with the error's own message when
+     * it rejects (the rejection still propagates).
+     */
+    step<T>(id: string, label: string, work: () => Promise<T>, detail?: (value: T) => string | undefined): Promise<T>;
+    /**
+     * Follows one job as part of step `id`. Jobs sharing an id (the same source
+     * searched for several queries) form one step that ends when the last one
+     * settles. The job's result and rejection pass through untouched.
+     */
+    track<T>(id: string, label: string, work: Promise<T>, options?: TrackOptions<T>): Promise<T>;
+    snapshot(): SearchProgressSnapshot;
+    /** Notified after every change. Not called on subscribe: read {@link snapshot} for the current state. */
+    subscribe(listener: (snapshot: SearchProgressSnapshot) => void): () => void;
+    private open;
+    private emit;
+}
+/** `7s` under a minute, `1:01` after. */
+export declare function formatElapsed(ms: number): string;
+/** Colour hooks for {@link renderSearchProgress}; pi's theme supplies them, tests pass identity. */
+export interface SearchProgressPalette {
+    readonly accent: (text: string) => string;
+    readonly muted: (text: string) => string;
+    readonly success: (text: string) => string;
+    readonly error: (text: string) => string;
+}
+/**
+ * The widget's lines at time `now`. Pure so the TUI and the tests render the
+ * same thing: a spinner header with the elapsed time, then one line per step.
+ * More steps than fit keep every running step and the newest finished ones.
+ */
+export declare function renderSearchProgress(snapshot: SearchProgressSnapshot, now: number, palette: SearchProgressPalette, width: number, interruptKey: string): string[];
+/**
+ * Binds the tracker to pi's widget slot: the widget appears when a search
+ * begins and disappears when it ends. `isCurrent` lets a replaced session's
+ * late notifications be dropped.
+ */
+export declare function bindSearchProgressWidget(ui: Pick<ExtensionUIContext, "setWidget">, tracker: SearchProgressTracker, interruptKey: () => string): () => void;
+/**
+ * pi extension that shows the tracker as a widget while a search runs. The
+ * widget slot is rebound on every `session_start` (resume, `/new`, fork) and
+ * released on shutdown, so a replaced session is never written to.
+ */
+export declare function createSearchProgressExtension(tracker: SearchProgressTracker, interruptKey: () => string): ExtensionFactory;

package/dist/agent/welcome-header.d.ts

@@ -0,0 +1,35 @@
+import type { ExtensionFactory, SettingsManager, Theme } from "@earendil-works/pi-coding-agent";
+/**
+ * One is shown per session, picked at random. Each fits on one line of an
+ * 80-column terminal after the `Tip · ` label, and is true of the TUI as shipped.
+ */
+export declare const WELCOME_TIPS: readonly string[];
+export interface WelcomeBannerOptions {
+    readonly width: number;
+    readonly version: string;
+    readonly theme: Pick<Theme, "fg" | "bold">;
+    /** Source of the rotating tip offset. Default `Math.random`. */
+    readonly random?: () => number;
+}
+/**
+ * The first screen of `autorag tui`: the logo, the version, and one random tip,
+ * centered on `width`. The logo is centered as one block so its shape holds;
+ * the version and the tip are centered on their own. The tip is always one line
+ * and is cut with `...` when the terminal is narrower than it.
+ */
+export declare function renderWelcomeBanner({ width, version, theme, random }: WelcomeBannerOptions): string[];
+/** The slice of pi's settings the banner reads and adjusts. */
+type WelcomeSettings = Pick<SettingsManager, "applyOverrides" | "getGlobalSettings" | "getProjectSettings" | "getQuietStartup">;
+export interface WelcomeHeaderOptions {
+    readonly version: string;
+    readonly settings: WelcomeSettings;
+    readonly random?: () => number;
+}
+/**
+ * Replaces pi's startup header (its logo, key hints) with the AutoRAG banner on
+ * every session start: launch, `/new`, `/resume`, `/fork`, `/reload`. pi
+ * restores its built-in header before each session start, so there is nothing
+ * to clean up. A user who saved `quietStartup: true` gets no banner.
+ */
+export declare function createWelcomeHeader(options: WelcomeHeaderOptions): ExtensionFactory;
+export {};

package/dist/cli/commands/setup.d.ts

@@ -1,2 +1,4 @@
+import { type SetupReport } from "../setup.js";
 import type { CommandContext } from "./types.js";
 export declare function runSetupCommand(ctx: CommandContext): Promise<number>;
+export declare function renderSetup(report: SetupReport): string;