@autorag/librarian 2.10.6 → 2.12.0

package/NOTICE

@@ -24,6 +24,9 @@ License: MIT
 @modelcontextprotocol/server@2.3.1
 License: Apache-2.0
 
+@parcel/watcher@2.6.0
+License: MIT
+
 chardet@2.2.0
 License: MIT
 
@@ -51,6 +54,9 @@ License: MIT
 pdfjs-dist@6.4.299
 License: Apache-2.0
 
+pi-ask-user@0.17.0
+License: MIT
+
 pi-discord-remote@0.2.4
 License: MIT
 
@@ -77,3 +83,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. Every tool call also carries a short model-written intent (the `i` argument): Pi's `Working` loader shows the newest one, and `autorag search` and the desktop app receive it as progress, so the model does not write separate progress notes before tool calls.
+
 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.
 
 ---
@@ -259,6 +263,7 @@ bun add @autorag/librarian
 - **Rust Toolchain (Optional):** Automatically compiles Jikji (`jikji-cli`) if installed.
 - **MinSync:** Automatically downloaded and installed into `<workspace>/.autorag/bin` on first run.
 - **Everything (Windows only, bundled):** The package ships the portable Everything 1.4.1.1032 and its ES 1.1.0.38 CLI (x64 and ARM64, SHA-256 pinned). On Windows, AutoRAG extracts them into `<workspace>/.autorag/everything/` and runs a private, user-level instance that indexes only your configured search roots: no administrator rights, no Everything service, no whole-drive scan, no HTTP/ETP server, and no change to any Everything you already run. Set `"everything": false` in the config to turn it off. macOS and Linux are not affected.
+- **filee-cli (file conversion, automatic):** `autorag setup` and the TUI download the pinned filee-cli release (~85 MB, SHA-256 verified) into `<AUTORAG_HOME>/tools/filee-cli/<version>/`, so the agent can convert between 255 formats offline with `convert_files`. A `filee`/`filee-cli` already on `PATH` is used instead. Set `"filee": { "autoInstall": false }` to forbid the download or `"filee": { "enabled": false }` to remove the tools. Filee fetches its own engines (FFmpeg, Pandoc, LibreOffice, calibre, Ghostscript; hundreds of MB, only when a conversion needs one) on first use.
 - **FSearch (macOS/Linux only, separate install):** Install [`fsearch-cli`](https://github.com/NomaDamas/fsearch-mac) yourself (e.g. `brew install NomaDamas/fsearch-mac/fsearch-mac` (installs the `fsearch-cli` binary); GPL-2.0, spawned as a separate process, never bundled or linked). On macOS and Linux, AutoRAG builds a per-workspace database at `<workspace>/.autorag/fsearch/` indexing only your configured search roots, and keeps a `fsearch-cli watch` daemon live (FSEvents/inotify) for sub-second name search. It never touches the FSearch app's own database. Without fsearch-cli, name search falls back to a slow bounded filesystem walk. Set `"fsearch": false` in the config to turn it off. Windows is not affected (Everything covers it).
 
 ---
@@ -471,7 +476,7 @@ mirrored are kept and not re-parsed on the next run. `onProgress` reports `parse
 | `autorag health` | Check model provider authentication, token validity, and API reachability |
 | `autorag models list` | List chat models the pi runtime can resolve (built-ins, `models.json`, custom/extension providers) with provider auth status; never prints credential values |
 | `autorag update-check` | Compare the running `autorag` against the published npm version (also runs on `autorag tui` launch) |
-| `autorag tui` | Open Pi's interactive librarian TUI (`/login`, `/model`, `/resume`, …); `--telegram` / `--whatsapp` / `--discord` add the Telegram / WhatsApp / Discord remote-control bridges |
+| `autorag tui` | Open Pi's interactive librarian TUI (`/login`, `/model`, `/resume`, …); the agent can stop and ask you a multiple-choice or open question through the [`ask_user` tool](docs/ask-user.md); `--telegram` / `--whatsapp` / `--discord` add the Telegram / WhatsApp / Discord remote-control bridges; `--permission-mode ask\|auto\|full` (Shift+Tab, `/permissions`) sets the [approval gate for file changes](docs/permissions.md) |
 | `autorag duplicates [DIR]` | Read-only scan for exact and near-duplicate document families with `dupey` |
 | `autorag lite ...` | CLI bootstrap, indexing repair, terminal maintenance, and fallback interface; agents use MCP for normal Lite operation |
 | `autorag memory inspect` | Render a read-only, path-opaque snapshot of retrieval memory (judged evidence, curated results, evidence chunks, insights); model-free |
@@ -501,6 +506,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 +619,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,15 +641,16 @@ 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.
+For configuration syntax and connector details, see [docs/datasource-skills.md](docs/datasource-skills.md). Non-interactive `sync`/`index` steps get a one-hour per-connector budget (`connector.indexTimeoutMs`) because first-run imports routinely take minutes; interactive search keeps its 60-second default.
 
 ---
 
@@ -692,7 +729,8 @@ 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.
-- **[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.
+- **[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.
 - **[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.
@@ -705,6 +743,7 @@ Deep dive into AutoRAG Agent's architecture, security, and integration guides:
 AutoRAG Agent is an open-source project built by the community. We welcome contributions, bug reports, datasource connectors, and ideas!
 
 - **Contributing:** Feel free to open an issue or pull request. Start with [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, the `make ci` check we ask for, the `Signed-off-by` trailer every commit needs, and when to run the live end-to-end lanes. [MAINTAINERS](MAINTAINERS) lists who reviews which area. AI tools are allowed; unverified dumps are not — see [AI_POLICY.md](AI_POLICY.md).
+- **Discussions:** For questions, usage help, ideas, and open-ended design talk, please use [GitHub Discussions](https://github.com/Marker-Inc-Korea/AutoRAG/discussions) instead of opening an issue. Keep issues for confirmed bugs and concrete, actionable work.
 - **Security:** Private vulnerability reports and the response SLA live in [SECURITY.md](SECURITY.md).
 - **GitHub Contributors:** [View all contributors](https://github.com/Marker-Inc-Korea/AutoRAG/graphs/contributors) on GitHub.
 
@@ -719,8 +758,10 @@ 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).
+- **[Filee](https://github.com/KnifeLemon/Filee)** by [KnifeLemon](https://github.com/KnifeLemon) — Offline conversion of 240+ file formats (MIT). Never bundled or linked: AutoRAG downloads the SHA-256-pinned [`filee-cli`](https://github.com/NomaDamas/filee-cli) release (NomaDamas' CLI-only redistribution, MIT) into `<AUTORAG_HOME>/tools/filee-cli/` on `autorag setup` / first conversion and spawns it as a separate process. An existing `filee`/`filee-cli` on `PATH` or `filee.binaryPath` wins. Filee downloads its own engines (FFmpeg, Pandoc, LibreOffice, …) on first use.
+- **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 +806,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 +817,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

@@ -1,5 +1,6 @@
 import type { Agent, AgentTool } from "@earendil-works/pi-agent-core";
 import type { Api, ImageContent, Model } from "@earendil-works/pi-ai";
+import { type FileeCliOptions, type FileeConvertRequest } from "../convert/index.js";
 import { type DatasourceRetryOptions } from "../datasource/retry.js";
 import type { DatasourceIndexResult, DatasourceSkill } from "../datasource/types.js";
 import { type DupeyCliOptions } from "../dupey/index.js";
@@ -15,10 +16,12 @@ import { RetrievalEngine } from "../retrieval/engine.js";
 import { RetrievalMethodRegistry } from "../retrieval/registry.js";
 import type { DatasourceCatalogEntry } from "../retrieval/selection.js";
 import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
+import { type ConvertFilesDetails } from "./convert-tool.js";
 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 { 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";
 import { type SearchDocumentDiagnostic, type SearchDocumentsResponse, type SearchDocumentsStreamEvent } from "./search-documents.js";
@@ -256,6 +259,12 @@ export interface AutoRAGAgentOptions {
     autoRefresh?: AutoRefreshOptions;
     parserOptions?: DefaultParserRegistryOptions;
     dupey?: DupeyCliOptions | false;
+    /**
+     * Filee command line behind `convert_files` and `list_file_conversions`.
+     * `false` leaves both tools out. The duplicate-family check on converted
+     * copies follows `dupey`.
+     */
+    filee?: FileeCliOptions | false;
     /**
      * Jev (TypeSafe's judgment model: typed questions in, calibrated
      * probabilities out). When set, the two-phase search asks Jev before the
@@ -345,6 +354,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. */
@@ -356,6 +367,15 @@ export interface AutoRAGAgentOptions {
      * owner pairing live in pi's `telegram.json`, never in AutoRAG config.
      */
     telegram?: boolean;
+    /**
+     * Approval gate for what the agent does to existing files. `full` (the programmatic default) installs a
+     * gate that never asks; `ask` and `auto` approve deletes, moves, renames, and in-place edits of originals
+     * (copying and creating new files never ask). `auto` asks Jev first and only falls back to the user when
+     * Jev will not approve. See {@link PermissionMode}.
+     */
+    permissionMode?: PermissionMode;
+    /** Share one controller (mode, session grants) with a host that switches modes itself. Wins over `permissionMode`. */
+    permissionController?: PermissionController;
 }
 /** Post-merge reranking options. Mirrors the CLI `RerankConfig` (secrets via env). */
 export interface RerankAgentOptions {
@@ -379,7 +399,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;
@@ -404,6 +424,8 @@ export declare class AutoRAGAgent {
     private readonly memory;
     private readonly runLogger;
     private lastQuery;
+    /** What the user has said in this conversation; Jev's permission gate judges file changes against it. */
+    private readonly userRequests;
     private lastSessionId;
     private activeRun;
     /**
@@ -414,6 +436,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;
@@ -424,6 +448,10 @@ export declare class AutoRAGAgent {
      * run starts from an empty ledger.
      */
     private readonly evidenceLedger;
+    /** The result numbers (`[n]`) this conversation has shown, kept next to the ledger's `e<N>` ordinals. */
+    private readonly citationNumbers;
+    /** Everything the user typed in this conversation; Jev reads it to judge whether a citation relates to what was asked. */
+    private readonly conversationQueries;
     private preliminaryCallback;
     /** Per-phase thinking levels of the two-phase search. */
     private readonly fastThinkingLevel;
@@ -456,10 +484,14 @@ export declare class AutoRAGAgent {
     private readonly datasourceAgentSkills;
     private readonly parserOptions;
     private readonly dupeyOptions;
+    private readonly fileeOptions;
     /** pi extension registering the optional `jev` tool; undefined when disabled. */
     private readonly jevExtension;
     /** Jev judge shared by the `jev` tool and the query router; undefined when disabled. */
     private readonly jevJudge;
+    /** Mode and grants of the file-change approval gate; shared by every pi session this agent creates. */
+    private readonly permissions;
+    private readonly permissionGate;
     /** Self-configuration, enabled only with Jev on a local session. */
     private readonly selfConfig;
     private readonly queryDecompositionModel;
@@ -475,6 +507,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;
@@ -492,11 +525,15 @@ export declare class AutoRAGAgent {
     /** The memory context loaded for the in-flight run; cleared whenever a run starts. */
     private memoryContextCache;
     private readonly discordRemote;
+    /** Whether the bound interactive session offers `ask_user`; the phase prompts name it only then. */
+    private askUserOffered;
     private activeRetrievalOptions;
     private readonly toolBurstGuard;
     private readonly limits;
     private readonly refreshLimits;
     constructor(options: AutoRAGAgentOptions);
+    convertFiles(request: FileeConvertRequest, signal?: AbortSignal): Promise<ConvertFilesDetails>;
+    listFileConversions(from?: string, signal?: AbortSignal): Promise<string>;
     scanDuplicateDocuments(): Promise<ScanDuplicateDocumentsDetails>;
     /**
      * Reference memory for the current question: everything judged earlier in
@@ -539,6 +576,8 @@ export declare class AutoRAGAgent {
     private configureSearchSession;
     private recordSearchToolEvent;
     private currentSystemPromptConfig;
+    /** The approval gate's controller: read or switch the permission mode of this agent's sessions. */
+    get permissionControl(): PermissionController;
     subscribe(listener: Parameters<Agent["subscribe"]>[0]): () => void;
     createPiInteractiveRuntime(): Promise<AutoRAGPiInteractiveRuntime>;
     /**
@@ -560,7 +599,12 @@ export declare class AutoRAGAgent {
      * matters, so the steer reaches the model before the next request.
      */
     private interruptibleBySteer;
-    /** Resolve the model's inline `[eN]` citations against this run's evidence and derive the structured results. */
+    /**
+     * Resolve the model's inline `[eN]` citations against this run's evidence and derive the structured results.
+     * With Jev on, every cited chunk is first checked for relevance to the sentence that cites it and to what
+     * the user typed in this conversation; a chunk Jev finds unrelated (a table of contents, a footer) is dropped
+     * from the citations before the answer is returned or judged for memory.
+     */
     private deriveAnswer;
     /**
      * Routes one TUI input the way pi routes typed input for its own turns. With
@@ -713,6 +757,12 @@ export declare class AutoRAGAgent {
      * continues on the retrieval-order fallback.
      */
     private reportRerankFailure;
+    /**
+     * Sentence for the phase prompts that forbid tool calls: `ask_user` is not a search tool, and a request
+     * that hinges on a choice only the user can make must be asked, not guessed. Empty when the session does
+     * not offer the tool.
+     */
+    private askUserException;
     /**
      * Fast-phase prompt for two-phase searches. The baseline retrieval context
      * is already gathered, so the model answers immediately with minimal thinking,
@@ -731,6 +781,24 @@ export declare class AutoRAGAgent {
      * reply is the final answer.
      */
     buildDirectAnswerPrompt(query: string): 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.
+     */
+    private organizeToolNames;
+    /**
+     * 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.
+     */
+    buildOrganizePrompt(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.
+     */
+    buildExtraPrompt(query: string): string;
     /** Discovery-tool hint naming only the registered discovery tools; empty when none. */
     private discoveryHint;
     /**

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

@@ -1,3 +1,4 @@
+import type { CitationNumbers } from "./citation-numbers.js";
 import { type EvidenceLedger } from "./evidence-ledger.js";
 import type { AutoRAGResultsDetails } from "./results.js";
 import type { SearchDocumentDiagnostic } from "./search-documents.js";
@@ -5,6 +6,31 @@ export interface DerivedAnswer {
     readonly details: AutoRAGResultsDetails;
     readonly diagnostics: readonly SearchDocumentDiagnostic[];
 }
+/**
+ * Identity of one cited chunk: the source plus the recorded chunk text. A
+ * source can back several chunks, so a chunk is judged and excluded on its own.
+ */
+export declare function citedChunkKey(ref: {
+    readonly source: string;
+    readonly content?: string;
+}): string;
+/** One chunk the answer cites, with the sentences that cite it. */
+export interface CitedChunk {
+    /** {@link citedChunkKey} of the chunk. */
+    readonly key: string;
+    readonly source: string;
+    readonly content: string;
+    /** Each distinct sentence ending in a marker that cites this chunk, in answer order. */
+    readonly sentences: readonly string[];
+}
+/**
+ * Every chunk the answer cites, read from the raw markers. It resolves ids the
+ * way {@link deriveResultsFromAnswer} does but numbers nothing, so judging a
+ * citation never touches the conversation's result numbers.
+ */
+export declare function citedChunks(text: string, ledger: EvidenceLedger, options: {
+    readonly allowLocalFiles: boolean;
+}): CitedChunk[];
 /**
  * Turn the model's plain answer into the structured results the rest of the
  * harness consumes. The model cites with the evidence ids the retrieval tools
@@ -12,11 +38,17 @@ export interface DerivedAnswer {
  * itself. Each id is resolved against the run's evidence ledger, so a source,
  * method, and chunk always come from recorded evidence, never from model text.
  *
- * Results are one per cited source, numbered by first appearance, and every
- * marker in the returned answer is rewritten to its result number (`[1]`).
+ * Results are one per cited source, in order of first appearance in this answer. A source's
+ * number comes from the conversation's {@link CitationNumbers}: a source
+ * numbered in an earlier answer (or an earlier phase of this turn) keeps its
+ * number, a new source gets the next unused one, and every marker in the
+ * returned answer is rewritten to its result number (`[1]`).
  * A marker that matches no evidence, and any numeric marker the model wrote on
  * its own, is dropped and reported: it can never point at the wrong result.
  */
 export declare function deriveResultsFromAnswer(text: string, ledger: EvidenceLedger, options: {
     readonly allowLocalFiles: boolean;
+    readonly numbers: CitationNumbers;
+    /** Chunks ({@link citedChunkKey}) a relevance judgment rejected: a citation of only these is dropped silently. */
+    readonly excludedChunks?: ReadonlySet<string>;
 }): DerivedAnswer;

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

@@ -10,11 +10,32 @@ 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
- * renumbers the markers `[1]`, `[2]`, ... in order of first appearance, so the
- * caller only ever sees numbered citations backed by recorded evidence.
+ * 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.";
 /**
@@ -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/ask-user.d.ts

@@ -0,0 +1,8 @@
+/** Tool the `pi-ask-user` extension registers; pi's allow-list must name it to keep it active. */
+export declare const ASK_USER_TOOL_NAME = "ask_user";
+/**
+ * Entry file of the community `pi-ask-user` extension (the most-installed pi package for this: Claude
+ * Code's AskUserQuestion, with a searchable single/multi-select sheet, freeform answers, and 2-4 question
+ * batches). It ships TypeScript source and no `main`, so pi's own extension loader runs it from this path.
+ */
+export declare function resolveAskUserExtensionPath(): string;

package/dist/agent/automation-tool.d.ts

@@ -0,0 +1,45 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+import type { AutomationRunRecord } from "../automation/run.js";
+import { type ServiceCommandExec } from "../automation/service.js";
+export declare const MANAGE_AUTOMATIONS_TOOL_NAME = "manage_automations";
+declare const manageAutomationsSchema: Type.TObject<{
+    action: Type.TUnion<[Type.TLiteral<"list">, Type.TLiteral<"save">, Type.TLiteral<"delete">, Type.TLiteral<"run">, Type.TLiteral<"install_service">, Type.TLiteral<"uninstall_service">]>;
+    id: Type.TOptional<Type.TString>;
+    automation: Type.TOptional<Type.TObject<{
+        paths: Type.TArray<Type.TString>;
+        events: Type.TOptional<Type.TArray<Type.TUnion<[Type.TLiteral<"create">, Type.TLiteral<"update">, Type.TLiteral<"delete">]>>>;
+        include: Type.TOptional<Type.TArray<Type.TString>>;
+        exclude: Type.TOptional<Type.TArray<Type.TString>>;
+        run: Type.TOptional<Type.TArray<Type.TString>>;
+        agent: Type.TOptional<Type.TObject<{
+            profile: Type.TString;
+            task: Type.TString;
+            retrieval: Type.TOptional<Type.TObject<{
+                searchAll: Type.TOptional<Type.TBoolean>;
+                datasources: Type.TOptional<Type.TArray<Type.TString>>;
+            }>>;
+        }>>;
+        appendFiles: Type.TOptional<Type.TBoolean>;
+        debounceMs: Type.TOptional<Type.TInteger>;
+        timeoutMs: Type.TOptional<Type.TInteger>;
+    }>>;
+    events: Type.TOptional<Type.TArray<Type.TObject<{
+        type: Type.TUnion<[Type.TLiteral<"create">, Type.TLiteral<"update">, Type.TLiteral<"delete">]>;
+        path: Type.TString;
+    }>>>;
+}>;
+export interface ManageAutomationsToolOptions {
+    readonly home?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly exec?: ServiceCommandExec;
+    readonly waitForRunningMs?: number;
+}
+export interface ManageAutomationsDetails {
+    readonly action: string;
+    readonly id?: string;
+    readonly run?: AutomationRunRecord;
+}
+export declare function createManageAutomationsTool(options?: ManageAutomationsToolOptions): AgentTool<typeof manageAutomationsSchema, ManageAutomationsDetails>;
+export {};

package/dist/agent/citation-links.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { type EvidenceLedger } from "./evidence-ledger.js";
+/** `file://` URL of an absolute local path, an http(s) URL as is, otherwise undefined (a datasource id, a message id). */
+export declare function openableTarget(source: string): string | undefined;
+/**
+ * Rewrite the citation markers of an assistant answer into Markdown links, so
+ * pi renders them as terminal hyperlinks that open the cited file or page.
+ *
+ * `[e3]` and `[e3, e7]` keep their brackets and ids; each id that resolves to
+ * an openable source becomes a link. `[file:/abs/path]` becomes `[<file name>]`
+ * linked to that file. Markers that resolve to nothing openable stay as the
+ * model wrote them.
+ *
+ * `sourceOf` maps an evidence id to its recorded source; `isFile` says whether
+ * a `[file:...]` path is a real local file.
+ */
+export declare function linkCitations(markdown: string, sourceOf: (id: string) => string | undefined, isFile: (path: string) => boolean): string;
+/**
+ * pi extension that makes the citations in the interactive transcript
+ * clickable. The model cites by evidence id; the ledger recorded the source
+ * each id names, so the link target is never model-written text.
+ */
+export declare function createCitationLinks(ledger: EvidenceLedger): ExtensionFactory;