@autorag/librarian 2.10.6 → 2.12.0

package/dist/retrieval/rerank.d.ts

@@ -33,6 +33,12 @@ export declare const DEFAULT_DAZZI_RERANK_MODEL = "qwen/qwen3-reranker-8b";
 export declare const DEFAULT_RERANK_TIMEOUT_MS = 60000;
 /** Default number of merged chunks kept after reranking. */
 export declare const DEFAULT_RERANK_TOP_N = 25;
+/**
+ * Longest document, in UTF-16 units, sent to a reranker. The hosted Dazzi
+ * reranker rejects a document of 131,072 characters or more with HTTP 400 and
+ * fails the whole request; 131,000 stays under that with a small margin.
+ */
+export declare const RERANK_MAX_DOCUMENT_CHARS = 131000;
 /** Rerank providers {@link createReranker} can build. */
 export declare const SUPPORTED_RERANK_PROVIDERS: readonly string[];
 /** Default wire model for a rerank provider. */

package/licenses/hister-AGPL-3.0-notice.txt

@@ -0,0 +1,47 @@
+Hister — license notice for AutoRAG's `hister` datasource
+==========================================================
+
+Program:      Hister ("Your own search engine")
+Source:       https://github.com/asciimoo/hister
+Copyright:    asciimoo and Hister contributors (see the repository history)
+License:      GNU Affero General Public License, version 3 or (at your option)
+              any later version (AGPL-3.0-or-later)
+License text: https://www.gnu.org/licenses/agpl-3.0.txt
+              (also the LICENSE file in the Hister repository)
+
+How AutoRAG relates to Hister
+-----------------------------
+* AutoRAG does NOT contain, bundle, link, vendor, or redistribute any Hister
+  source code or binary. Nothing from the Hister repository is copied into
+  this package.
+* Users install Hister themselves, unmodified, from its own releases
+  (https://github.com/asciimoo/hister/releases, `brew install hister`, Docker,
+  or Nix), and run it as a separate process (`hister listen`).
+* AutoRAG talks to that process only over HTTP, using Hister's public JSON API
+  (`GET /search`, `GET /api/config`), the same API Hister's own `hister search`
+  command uses. Hister owns its index, its browser extension, its credentials,
+  and its optional embedding calls.
+* AutoRAG does not modify Hister, and it never hides that Hister is the backend:
+  the datasource manifest shown to the agent names Hister, its license, and its
+  source URL.
+* The `hister` datasource only reads web-page documents (`type:web`). It never
+  enables or uses Hister's local-directory indexing.
+
+Combining separate programs that communicate over a network is "mere
+aggregation" in the sense of the GNU licenses FAQ
+(https://www.gnu.org/licenses/gpl-faq.html#MereAggregation); AutoRAG therefore
+stays under its own license (Apache-2.0).
+
+If you run Hister as a network service for other people, AGPL-3.0 section 13
+applies to YOU as the operator of that Hister instance: you must offer those
+users the Corresponding Source of the Hister version you run (and of any
+modifications you made). Running an unmodified upstream release satisfies this
+by pointing users at https://github.com/asciimoo/hister.
+
+Obtaining the Hister source for a release you run
+-------------------------------------------------
+    git clone https://github.com/asciimoo/hister
+    git checkout <the version printed by `hister --version`>
+
+This file is a notice, not the license. The authoritative license terms are in
+the Hister repository and at the AGPL URL above.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.10.6",
-  "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
+  "version": "2.12.0",
+  "description": "Personal librarian agent for office work on the Pi framework, with pluggable retrieval methods",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -18,6 +18,10 @@
     "./core": {
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
+    },
+    "./profiles": {
+      "types": "./dist/profiles.d.ts",
+      "default": "./dist/profiles.js"
     }
   },
   "bin": {
@@ -36,7 +40,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build src/index.ts src/core.ts src/cli/index.ts src/mcp/index.ts src/parser/parse-worker.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
+    "build": "bun build src/index.ts src/core.ts src/profiles.ts src/cli/index.ts src/mcp/index.ts src/parser/parse-worker.ts --outdir dist --target node --packages external && tsc -p tsconfig.build.json && node scripts/fixup-dts.mjs",
     "prepublishOnly": "bun run typecheck && bun run build",
     "prepare": "bun run build",
     "test": "node scripts/run-test-files.mjs",
@@ -56,6 +60,7 @@
     "@earendil-works/pi-tui": "1.2.0",
     "@llblab/pi-telegram": "0.57.2",
     "@modelcontextprotocol/server": "^2.3.1",
+    "@parcel/watcher": "2.6.0",
     "chardet": "^2.2.0",
     "discord.js": "14.27.0",
     "fast-xml-parser": "^5.11.2",
@@ -65,6 +70,7 @@
     "kordoc": "^4.21.30",
     "mailparser": "^3.9.38",
     "pdfjs-dist": "^6.4.299",
+    "pi-ask-user": "0.17.0",
     "pi-discord-remote": "0.2.4",
     "puppeteer-core": "^25.13.0",
     "slides-grab": "^1.5.2",

package/skills/autorag/SKILL.md

@@ -15,10 +15,13 @@ search, calls MinSync, Jikji, datasource, and filesystem tools, reads
 sources, judges evidence, and curates the final answer. There is no subagent or
 separate model role.
 
-AutoRAG reads source documents and writes indexes only under the configured
+Indexing and refresh read source documents and write only under the configured
 workspace `.autorag/` directory and Jikji's central store (`<OS data dir>/jikji/`,
-plus a `.jikji_agent_map.md` guide in each indexed root). Never
-move, rename, edit, or delete source files.
+plus a `.jikji_agent_map.md` guide in each indexed root). The librarian may
+organize, create, or modify the user's own files in local sessions when the
+user asks; it never deletes permanently (OS trash only) and lists every change
+as old path → new path. Do not move, rename, edit, or delete source files on your own
+initiative while searching or diagnosing.
 
 ## Preflight
 
@@ -42,6 +45,34 @@ near/contains families require human review. Exact duplicate exclusion during
 refresh is enabled by default and can be disabled with
 `"excludeExactDuplicates": false` in `config.json`.
 
+### Converting files
+
+The `convert_files` and `list_file_conversions` Agent tools run the
+[Filee](https://github.com/KnifeLemon/Filee) command line to convert local
+files offline: documents, spreadsheets, slides, HWP/HWPX, images, e-books,
+archives, audio, video, data, and subtitles. They work on any path the user
+names, not only the configured roots. This is the one exception to the
+"never write source files" rule above: a conversion writes a new file and
+never touches its source. An existing output name gets a number added unless
+the user asks to replace it, in which case pass `overwrite: true`. Never
+delete the source unless the user asked.
+
+Each converted file is checked with `dupey compare` against its source, using
+dupey's own thresholds, so the report says whether a later scan will group
+them: `exact` (same canonical text, for example DOCX to HWPX), `near` (same
+document in another format, for example Markdown to TXT), `different` (text
+differs, typically layout formats such as PDF), `unsupported` (dupey cannot
+read the format, for example HTML or images), or `unavailable` (dupey not
+installed). The command line is `filee.binaryPath` if set, else a `filee`/`filee-cli`
+on `PATH`, else the pinned [filee-cli](https://github.com/NomaDamas/filee-cli)
+release that `autorag setup` (or the first conversion) downloads into
+`<AUTORAG_HOME>/tools/filee-cli/`; `"filee": { "autoInstall": false }` forbids that
+download. The system prompt carries the conversion map (which format family
+converts to which, and the two-step chain when no direct route exists), so plan
+from it instead of probing. `"filee": { "enabled": false }` in `config.json` removes both
+tools; `filee.timeoutMs` (default 30 minutes) and `filee.dataDir` (Filee's
+own settings and engines, `FILEE_DATA_DIR`) tune them.
+
 ### Excluding local files from the index
 
 `"excludePaths"` in `config.json` lists files or folders (absolute, or relative
@@ -80,7 +111,10 @@ autorag search "what were the key findings in the Q3 report" --top-k 5 --json --
 only `answer` plus `results`. Every
 bracketed `[n]` citation in `answer` resolves to a `results[].number` of the
 same response; an unmatched citation is removed and reported as a
-`citation-without-result` diagnostic.
+`citation-without-result` diagnostic. Within one conversation (an interactive
+session, including a resumed one), a source keeps the `number` it was first
+shown with and a new source gets the next unused number, so `results[].number`
+can skip numbers and need not start at 1 on a later turn.
 
 To inspect the exact persisted evidence behind numbered results, use:
 
@@ -113,7 +147,13 @@ default, OpenRouter), Jev first routes the question:
   datasources) is handled by the agent itself: it loads the setup skill, edits
   the active config, verifies it, and reports what changed. The running agent
   keeps its startup model; changes apply to the next `autorag` launch.
-- Private-data questions use local search; public current facts use web search.
+- A request to act on files or folders (move, bulk rename, rename by content,
+  convert, sort) is carried out in one tool turn with no retrieval and no
+  verification, and reports every change as old path → new path.
+- Anything else that needs no retrieval (commit, push, open a PR, run a build)
+  is carried out in one tool turn the same way.
+- Private-data questions use local search; the agent decides on web search
+  after the fast answer.
 - A multi-part question is split into up to five parallel search queries.
 - On local search, Jev also picks which registered datasources (Slack,
   Discord, KakaoTalk, email, ...) to search before the fast answer, from each
@@ -142,8 +182,42 @@ autorag index rebuild --yes --json
 autorag index reset --method parsed --yes --json
 autorag memory inspect --json
 autorag tui
+autorag automate status --json
+autorag automate install --json
+autorag automate uninstall --json
+autorag automate run invoice --event create:/path/to/file.pdf --json
+autorag automate daemon
+```
+
+File-triggered automations live in `~/.autorag/automations.json` (`automations`
+array of `{ id, paths, events, include, exclude, run | agent, appendFiles, debounceMs, timeoutMs }`).
+Edit `automations.json` directly to add or change rules; matched `[{ type, path }]`
+events are piped on stdin to `run`. Use `autorag automate install` to register
+the background daemon with launchd, `systemd --user`, or Windows Task Scheduler.
+
+A rule runs exactly one of `run` (a command) or `agent` (an AI agent started in
+the daemon on each batch of changes):
+
+```json
+{ "id": "inbox-triage", "paths": ["~/Downloads"], "include": ["**/*.pdf"],
+  "agent": { "profile": "file-triage", "task": "Summarize each new PDF.",
+             "retrieval": { "searchAll": true, "datasources": ["kakao"] } } }
 ```
 
+`agent.profile` names a profile defined in code: `file-triage` (reads, lists and
+searches files; changes nothing) or `file-organizer` (also `bash`, `edit`,
+`write`). A rule never carries a prompt or a tool list, so the rules file cannot
+grant an agent more than its profile has. `retrieval` optionally adds
+`search_all_documents` and one `search_datasource_<id>` per listed datasource.
+Retrieval memory is never connected to an automation agent.
+
+Every agent run gets a loop guard appended to its system prompt, naming the
+rule's folders, file types and events, and forbidding any change that would
+fire the rule again, editing the rules file, and running `autorag automate`. At
+most one agent run is in flight across all rules, and an agent rule is
+disabled after 6 runs within 60 seconds (command rules: 20). The run's final
+reply is the `stdout` of its log entry.
+
 Prefer a full refresh so parsed mirrors, MinSync, Jikji, configured
 datasources, and (on Windows) the bundled Everything file-name index stay
 aligned. `--method` accepts

package/skills/autorag-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autorag-doctor
-description: Diagnose and repair a broken or half-working AutoRAG install so every configured source is both indexed and searchable. Checks AutoRAG, MinSync, Jikji, the embedding backend, and every CLI-backed datasource (lazykatok, discrawl, slacrawl, wacrawl, telecrawl, notcrawl, qmd, mailcrawl, rclone, Spotlight), then fixes orphan locks, orphan processes, embedding dimension or identity mismatches, stale indexes, and missing setup. Use when search returns nothing or too little, refresh hangs or fails, a datasource disappeared from results, indexes look stale, the embedder is unavailable, or the user asks to check, diagnose, verify, or repair AutoRAG.
+description: Diagnose and repair a broken or half-working AutoRAG install so every configured source is both indexed and searchable. Checks AutoRAG, MinSync, Jikji, the embedding backend, and every CLI-backed datasource (lazykatok, discrawl, slacrawl, wacrawl, telecrawl, notcrawl, mailcrawl, rclone, Spotlight), then fixes orphan locks, orphan processes, embedding dimension or identity mismatches, stale indexes, and missing setup. Use when search returns nothing or too little, refresh hangs or fails, a datasource disappeared from results, indexes look stale, the embedder is unavailable, or the user asks to check, diagnose, verify, or repair AutoRAG.
 license: Apache-2.0
 ---
 
@@ -15,9 +15,10 @@ Always finish with the status table in [Report](#report).
 
 ## Safety
 
-- Never delete, move, or edit source documents.
+- Diagnosis and repair never delete, move, or edit source documents; a doctor
+  run changes only AutoRAG-owned state.
 - Never delete a datasource's **native** store (`~/Library/Application Support/katok`, `~/.discrawl`,
-  `~/.mailcrawl`, `.qmd`, Telegram/WhatsApp/Notion archives). AutoRAG only
+  `~/.mailcrawl`, Telegram/WhatsApp/Notion archives). AutoRAG only
   reads them; rebuilding them is the owning CLI's job.
 - Only AutoRAG-owned state under `AUTORAG_HOME` and the workspace `.autorag`
   directory may be reset.
@@ -69,7 +70,7 @@ Each CLI owns its archive, so ask the CLI, not AutoRAG. A datasource is only
 | WhatsApp | `wacrawl --json doctor` | `wacrawl import` |
 | Telegram | `telecrawl --json doctor`, `telecrawl --json status` | `telecrawl import` |
 | Notion | `notcrawl doctor`, `notcrawl status` | `notcrawl sync --source desktop` |
-| Obsidian / notes | `qmd status` | `qmd update && qmd embed` |
+| Obsidian / notes | `autorag status` (AutoRAG-owned index) | `autorag refresh --method datasources`; if corrupt, delete `.autorag/datasources/obsidian/<instance>` first |
 | Mail | `mailcrawl doctor`, `mailcrawl status` | `mailcrawl sync && mailcrawl index` |
 | Cloud drive | `rclone listremotes` | `autorag refresh --method datasources` |
 | Spotlight (macOS) | `mdutil -s /` | indexed by the OS; no AutoRAG sync |

package/skills/autorag-lite-setup/SKILL.md

@@ -17,9 +17,9 @@ Use `autorag-setup` instead when the model-backed librarian must be configured.
   `memoryPath`, `minSync`, `jikji`, `datasources`.
 - Never print, copy, migrate, compare, or persist credential values. Store only
   environment-variable names such as `tokenEnv` or `apiKeyEnv`.
-- Never move, rename, edit, or delete source documents. Lite commands write
-  indexes only under the configured workspace `.autorag/` directory and
-  Jikji's central store (`<OS data dir>/jikji/`).
+- Setup and Lite commands never move, rename, edit, or delete source documents.
+  They write indexes only under the configured workspace `.autorag/` directory
+  and Jikji's central store (`<OS data dir>/jikji/`).
 - Do not index system trees, app bundles, caches, credential stores,
   `node_modules`, `.git`, `dist`, `build`, `target`, `.cache`, `.autorag`, or
   `.jikji`.
@@ -113,7 +113,7 @@ setup. Configure datasources directly in trusted config, wizard-style:
 
 1. Probe every datasource for setup feasibility before asking the user
    anything: the backing CLI exists (`lazykatok`, `discrawl`, `slacrawl`,
-   `wacrawl`, `telecrawl`, `notcrawl`, `qmd`, `mailcrawl`, `rclone`) and its
+   `wacrawl`, `telecrawl`, `notcrawl`, `mailcrawl`, `rclone`) and its
    local store or archive is present. CLI-backed datasources own their own
    archive, index, and authentication, so environment credentials (such as bot
    tokens) are never required or checked for them. Non-CLI connectors
@@ -137,7 +137,7 @@ Datasource skills belong in trusted config.
 
 Config keys may be builtin template names (`kakao`, `whatsapp`, `telegram`,
 `slack`, `discord`, `clawgallery`, `notion`, `github`, `cloud-drive`,
-`mail-export`, `mailcrawl`, `obsidian`, `rss`, `spotlight`, `lark`) or connection
+`mail-export`, `mailcrawl`, `obsidian`, `rss`, `spotlight`, `lark`, `hister`) or connection
 aliases with `"type": "<template>"`. Unknown names are skipped with an
 `unknown-datasource-skill` warning; they do not fail config resolution.
 `scope` narrows a query to a sub-path as ordinary filtering. Tags are
@@ -146,6 +146,24 @@ select configured connections before retrieval; discover their IDs with
 `autorag.datasources.list`. Store only env-var names such as `tokenEnv` or
 `apiKeyEnv`, never credential values.
 
+### Browser history (Hister) and the shared embedding model
+
+`hister` needs a separately installed, always-running Hister server (AGPL-3.0, never
+bundled by AutoRAG). Run `autorag setup --format json` and read the `hister` object
+(`installed`, `running`, `embedding`); each problem carries the exact command to run:
+`brew install hister`, `brew services start hister`, then install the Hister browser
+extension in the user's browser.
+
+Hister embeds with its own `semantic_search` config, so it must use the same model as
+AutoRAG (the `minsync serve` daemon, `Qwen/Qwen3-Embedding-0.6B`, 1024 dimensions) or
+its vectors stop lining up without any error. `autorag setup --sync-hister` copies the
+shared settings into Hister's `config.yml` (backup kept), restarts the service, waits
+for it, and runs `hister reindex` when needed; it is idempotent, and it refuses a
+remote or in-process backend. Re-run it after restarting the `minsync serve` daemon
+(its port changes). Verify with `hister doctor`: `server.index.embeddings` must be `ok`.
+Install a skip list in Hister's `rules.json` before importing past history, because the
+importer re-downloads URLs without the browser's cookies (docs/datasource-skills.md).
+
 ## Build and refresh indexes
 
 After connecting, call MCP `autorag.refresh` with `{}` for an incremental run.

package/skills/autorag-setup/SKILL.md

@@ -21,7 +21,8 @@ librarian, not the Lite MCP server.
 - Never print, copy, migrate, compare, or persist credential values. Store only
   environment-variable names such as `apiKeyEnv`.
 - Do not scan the whole filesystem or home directory without explicit approval.
-- Never move, rename, edit, or delete source documents.
+- Setup, indexing, and refresh never move, rename, edit, or delete source
+  documents. The librarian itself may organize files when the user asks it to.
 - Do not index system trees, app bundles, caches, credential stores,
   `node_modules`, `.git`, `dist`, `build`, `target`, `.cache`, `.autorag`, or
   `.jikji`.
@@ -200,7 +201,7 @@ resolves in order:
 
 1. A configured remote endpoint (`minSync.embedder`), used for everything; no
    daemon is started and no local model is loaded.
-2. A running `minsync serve` daemon (loopback only; MinSync 0.4.11+).
+2. A running `minsync serve` daemon (loopback only; MinSync 0.4.12+).
    AutoRAG never starts it: run `minsync serve --idle-timeout 0` yourself, as
    a launchd/systemd service (see `docs/minsync-setup.md`), or press
    Ctrl+Shift+E in `autorag tui`. `autorag setup` only reports whether it is
@@ -238,9 +239,11 @@ fast and multi-part questions thorough.
 - **Jev** (`jev`, default `{ "backend": "dazzi" }` when signed in to Dazzi
   Models, else `{ "backend": "openrouter" }`; model `jev-1.13` on Dazzi,
   `typesafe/jev-1.13` on OpenRouter) runs before the fast answer. It routes each question to
-  local search, web search, a direct answer (general knowledge or small
-  talk skips retrieval entirely), or the `config` branch, and decides whether
-  to decompose it. On
+  local search, a direct answer (general knowledge or small
+  talk skips retrieval entirely), `organize` (moving, renaming, converting, or
+  sorting files and folders), `extra` (any other action that needs no
+  retrieval, such as committing code), or the `config` branch, and decides
+  whether to decompose it. On
   local search it also decides, per registered datasource, whether to search
   it before the fast answer, using each datasource's `description` and where
   similar past questions were answered (retrieval memory). When setting up a
@@ -361,7 +364,7 @@ setup. Configure datasources directly in trusted config, wizard-style:
 
 1. Probe every datasource for setup feasibility before asking the user
    anything: the backing CLI exists (`lazykatok`, `discrawl`, `slacrawl`,
-   `wacrawl`, `telecrawl`, `notcrawl`, `qmd`, `mailcrawl`, `rclone`, `lark-cli`) and its
+   `wacrawl`, `telecrawl`, `notcrawl`, `mailcrawl`, `rclone`, `lark-cli`) and its
    local store or archive is present. CLI-backed datasources own their own
    archive, index, and authentication, so environment credentials (such as bot
    tokens) are never required or checked for them. Non-CLI connectors
@@ -384,7 +387,7 @@ setup. Configure datasources directly in trusted config, wizard-style:
 Datasource skills belong in trusted config. Builtin
 template names are `kakao`, `whatsapp`, `telegram`, `slack`, `discord`,
 `clawgallery`, `notion`, `github`, `github-gist`, `cloud-drive`, `mail-export`,
-`mailcrawl`, `obsidian`, `rss`, `spotlight`, and `lark`. Config keys may be connection
+`mailcrawl`, `obsidian`, `rss`, `spotlight`, `lark`, and `hister`. Config keys may be connection
 aliases with `"type": "<template>"`. Unknown names are skipped with an
 `unknown-datasource-skill` warning; they do not fail config resolution.
 `scope` narrows a query to a sub-path as ordinary filtering. Tags are descriptive metadata only, not search filters. MCP `datasourceIds` selects configured connections before retrieval; discover their IDs with `autorag.datasources.list`.
@@ -418,6 +421,62 @@ the next `index`. kakao needs `lazykatok` 0.3.3 or newer for the same reason.
 Use mailcrawl for Gmail, IMAP, and Maildir retrieval. The former Gmail REST
 datasource is removed.
 
+### Browser history (Hister) and the shared embedding model
+
+`hister` is the one datasource whose backing program AutoRAG does not install,
+start, or bundle (it is AGPL-3.0-or-later and stays a separate program). Setting
+it up is an agent task with these steps. Run each command; do not just describe it.
+
+1. **Probe first.** Add the datasource entry, then run `autorag setup --format json`
+   and read the `hister` object: `installed`, `running`, and `embedding`. Every
+   problem has a `remediation` string with the exact next command.
+2. **Install Hister** when `installed` is false: `brew install hister` (other
+   platforms: the release binaries at https://github.com/asciimoo/hister/releases).
+3. **Run it as a login item** when `running` is false: `brew services start hister`.
+   Hister must stay running: its browser extension only captures while it is up,
+   and a page visited while it is down is not re-sent. AutoRAG never starts it.
+4. **Install the browser extension** (Chrome Web Store "Hister", or Firefox
+   Add-ons). It must be done in the user's browser; tell the user if you cannot.
+5. **Share the embedding model** (below).
+6. **Before importing past history, install a skip list** in Hister's `rules.json`
+   (login, mail, documents, social and console domains, private hosts, token-bearing
+   URLs). `hister import browser history` re-downloads each URL *without* the
+   browser's cookies. See docs/datasource-skills.md, "Browser history via Hister".
+7. Add `"browser": { "type": "hister", "connector": { "semantic": true } }` under
+   `datasources`, then `autorag refresh` (only probes Hister) and
+   `autorag lite retrieve "<a question>" --scope '/browser/**' --json`.
+
+**Shared embedding model.** Hister keeps its own vector store and embeds with
+whatever its `config.yml` `semantic_search` block says. Pointing it at a different
+model does not fail: vectors simply stop lining up and results get worse. So Hister
+must use the same model as AutoRAG, which is the `minsync serve` daemon (model
+`Qwen/Qwen3-Embedding-0.6B`, 1024 dimensions, with Qwen3's query instruction).
+
+```bash
+autorag setup --format json            # reports hister.embedding.differs: the keys that disagree
+autorag setup --sync-hister            # writes them, restarts Hister, re-embeds pages if needed
+```
+
+- `--sync-hister` rewrites only `enable`, `embedding_endpoint`, `embedding_model`,
+  `dimensions`, `query_prefix`, `document_prefix` in Hister's config (a
+  `config.yml.bak.<time>` is kept next to it), then runs `brew services restart hister`,
+  waits for it to answer, and runs `hister reindex` when a change makes stored
+  vectors stale. Without the flag setup never writes Hister's config.
+- The daemon port is chosen when `minsync serve` starts. After restarting the daemon,
+  run `autorag setup --sync-hister` again. It is idempotent: when nothing differs
+  it changes nothing and restarts nothing.
+- It refuses, and says why, when the shared backend is a remote endpoint (browsing
+  text would leave the machine) or MinSync's in-process engine (Hister cannot reach
+  it; run `minsync serve --idle-timeout 0`, docs/minsync-setup.md).
+- If `restartRequired` or `reindexRequired` is true in the report, the step was
+  not done (no Homebrew service, or it failed): run `brew services restart hister`
+  and `hister reindex` yourself. Check with `hister doctor`: the line
+  `server.index.embeddings` must be `ok`.
+- A changed `query_prefix` alone needs a restart but no reindex. Never hand-edit the
+  `query_prefix` value across two lines: Hister's YAML parser folds the newline into
+  a space and the model's instruction is silently corrupted. `--sync-hister` writes
+  it correctly.
+
 ## Verify and build indexes
 
 Configuration alone is not a successful setup:
@@ -483,6 +542,8 @@ is set up.
 - `AUTORAG_MEMORY_PATH`
 - `AUTORAG_MODEL_PROVIDER`
 - `AUTORAG_MODEL_ID`
+- `AUTORAG_PERMISSION_MODE` (`auto` default for the TUI, `full` for `autorag search` and a TUI with a chat bridge, `ask`, `full`; config key `permissionMode`; with `auto` Jev checks the agent's
+  file-changing calls and asks the user only when it will not approve, `ask` asks about every one, `full` never asks)
 
 ## Completion condition
 

package/dist/datasource/skills/obsidian/client.d.ts

@@ -1,15 +0,0 @@
-import type { QmdEmbedResult, QmdEnsureResult, QmdOptions, QmdSearchMode, QmdSearchOptions, QmdSearchResult, QmdUpdateResult } from "./types.js";
-/**
- * Thin external `qmd` CLI wrapper for Obsidian vault indexing/search.
- * Every method spawns the `qmd` binary, never throws for expected failures,
- * and isolates config/cache under the AutoRAG workspace.
- */
-export declare class QmdClient {
-    private readonly options;
-    constructor(options?: QmdOptions);
-    ensureCollection(signal?: AbortSignal): Promise<QmdEnsureResult>;
-    update(signal?: AbortSignal): Promise<QmdUpdateResult>;
-    embed(signal?: AbortSignal): Promise<QmdEmbedResult>;
-    search(mode: QmdSearchMode, query: string, options?: QmdSearchOptions): Promise<QmdSearchResult>;
-    private run;
-}

package/dist/datasource/skills/obsidian/types.d.ts

@@ -1,92 +0,0 @@
-import type { RetrievalOptions } from "../../../retrieval/types.js";
-/**
- * Search modes accepted by the external `qmd` CLI.
- *
- * - `search`  — BM25 / FTS5 lexical search
- * - `vsearch` — dense vector semantic search
- */
-export type QmdSearchMode = "search" | "vsearch";
-/**
- * Configuration for {@link QmdClient}. The client spawns the `qmd` binary as a
- * child process and isolates config/cache under the AutoRAG workspace.
- */
-export interface QmdOptions {
-    /** Explicit path to the `qmd` binary. Defaults to a bare `qmd` PATH lookup. */
-    readonly binaryPath?: string;
-    /** Spawn timeout in milliseconds. Default 60_000 (embed can be slow). */
-    readonly timeoutMs?: number;
-    /** Max stdout/stderr bytes retained. Default 1_048_576 (1 MiB). */
-    readonly maxBufferBytes?: number;
-    /** Absolute path to the Obsidian vault. Required for ensure/update. */
-    readonly vaultPath?: string;
-    /** AutoRAG workspace root used to isolate qmd config/cache. */
-    readonly workspaceRoot?: string;
-    /** Instance id used for source paths and collection naming. Default `default`. */
-    readonly instanceId?: string;
-    /** Explicit collection name; defaults to a sanitized instance id. */
-    readonly collectionName?: string;
-    /** Environment overrides merged on top of a restricted process env. */
-    readonly env?: Readonly<Record<string, string | undefined>>;
-    /** Explicit operator-owned qmd config directory, never rewritten. */
-    readonly configPath?: string;
-}
-export declare const DEFAULT_QMD_BINARY = "qmd";
-export declare const DEFAULT_QMD_TIMEOUT_MS = 60000;
-export declare const DEFAULT_QMD_MAX_BUFFER_BYTES = 1048576;
-export type QmdFailureReason = "binary-missing" | "not-configured" | "nonzero-exit" | "spawn-error" | "timeout" | "aborted" | "stdout-too-large" | "stderr-too-large" | "invalid-json" | "invalid-shape";
-export interface QmdFailure {
-    readonly ok: false;
-    readonly reason: QmdFailureReason;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly code: number | null;
-}
-export interface QmdOk<T> {
-    readonly ok: true;
-    readonly data: T;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly code: number;
-}
-export interface QmdUpdateInfo {
-    readonly indexed: number;
-    readonly updated: number;
-    readonly unchanged: number;
-    readonly removed: number;
-    readonly needsEmbedding?: boolean;
-    readonly metadata?: Readonly<Record<string, unknown>>;
-}
-export interface QmdEmbedInfo {
-    readonly embedded: boolean;
-    readonly metadata?: Readonly<Record<string, unknown>>;
-}
-export interface QmdEnsureInfo {
-    readonly collectionName: string;
-    readonly vaultPath: string;
-    readonly configDir: string;
-}
-/** A scored search hit from `qmd search` / `qmd vsearch`. */
-export interface QmdSearchHit {
-    readonly chunkId: string;
-    readonly score: number;
-    readonly content: string;
-    readonly title?: string;
-    readonly file?: string;
-    readonly docid?: string;
-    readonly metadata?: Readonly<Record<string, unknown>>;
-}
-export interface QmdSearchOk {
-    readonly ok: true;
-    readonly hits: readonly QmdSearchHit[];
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly code: number;
-    readonly data: {
-        readonly hits: readonly QmdSearchHit[];
-    };
-}
-export type QmdEnsureResult = QmdOk<QmdEnsureInfo> | QmdFailure;
-export type QmdUpdateResult = QmdOk<QmdUpdateInfo> | QmdFailure;
-export type QmdEmbedResult = QmdOk<QmdEmbedInfo> | QmdFailure;
-export type QmdSearchResult = QmdSearchOk | QmdFailure;
-export type QmdSearchOptions = RetrievalOptions;