@autorag/librarian 2.10.6 → 2.11.0

package/dist/datasource/errors.d.ts

@@ -6,7 +6,7 @@
  * pipeline reports the surface as unsearched and hands the operator the CLI's
  * own words: failure kind, exit status, and stderr verbatim.
  */
-/** The failure payload every datasource CLI client returns (lazykatok, discrawl, qmd, …). */
+/** The failure payload every datasource CLI client returns (lazykatok, discrawl, mailcrawl, …). */
 export interface DatasourceCliFailure {
     readonly reason: string;
     readonly stderr?: string;

package/dist/datasource/index.d.ts

@@ -10,13 +10,14 @@ export { CLOUD_DRIVE_SKILL_DEFINITION, CloudDriveSkill, type CloudDriveSkillOpti
 export { DEFAULT_DISCRAWL_EMBEDDING_MODEL, DEFAULT_DISCRAWL_MODE, DiscrawlClient, type DiscrawlFailureReason, DiscrawlFtsMethod, DiscrawlHybridMethod, type DiscrawlOptions, type DiscrawlSearchHit, type DiscrawlSearchMode, type DiscrawlSearchOptions, type DiscrawlSearchResult, DiscrawlSemanticMethod, DiscrawlSkill, type DiscrawlSkillClient, type DiscrawlSkillOptions, ENGLISH_ONLY_EMBEDDING_MODELS, } from "./skills/discrawl/index.js";
 export { BUILTIN_DATASOURCE_SKILL_NAMES, type BuildDatasourceSkillsResult, buildDatasourceSkills, type DatasourceSkillConfig, type DatasourcesConfig, } from "./skills/factory.js";
 export { GitHubConnector, type GitHubConnectorOptions, GitHubSkill, type GitHubSkillOptions, } from "./skills/github/index.js";
+export { HISTER_SKILL_TYPE, HisterClient, type HisterClientOptions, HisterSkill, type HisterSkillOptions, } from "./skills/hister/index.js";
 export { LarkClient, type LarkClientOptions, LarkSkill, type LarkSkillOptions } from "./skills/lark/index.js";
 export type { LazykatokFailureReason, LazykatokHit, LazykatokOptions, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSkillClient, LazykatokSkillOptions, } from "./skills/lazykatok/index.js";
 export { LazykatokBm25Method, LazykatokClient, LazykatokSemanticMethod, LazykatokSkill, } from "./skills/lazykatok/index.js";
 export { MailExportConnector, type MailExportConnectorOptions, MailExportSkill, type MailExportSkillOptions, } from "./skills/mail-export/index.js";
 export { MAILCRAWL_MODES, MailcrawlClient, type MailcrawlFailure, type MailcrawlFailureReason, type MailcrawlIndexInfo, MailcrawlMethod, type MailcrawlOptions, type MailcrawlSearchHit, type MailcrawlSearchMode, type MailcrawlSearchResult, MailcrawlSkill, type MailcrawlSyncInfo, type MailcrawlSyncResult, } from "./skills/mailcrawl/index.js";
 export { NotcrawlClient, type NotcrawlOptions, NotionSkill, type NotionSkillOptions, } from "./skills/notion/index.js";
-export { ObsidianBm25Method, ObsidianSemanticMethod, ObsidianSkill, type ObsidianSkillClient, type ObsidianSkillOptions, QmdClient, type QmdOptions, type QmdSearchHit, type QmdSearchMode, type QmdSearchResult, } from "./skills/obsidian/index.js";
+export { ObsidianBm25Method, type ObsidianMethodOptions, ObsidianSemanticMethod, ObsidianSkill, type ObsidianSkillOptions, } from "./skills/obsidian/index.js";
 export { RssConnector, type RssConnectorOptions, type RssFeedConfig, RssSkill, type RssSkillOptions, } from "./skills/rss/index.js";
 export { SlackSkill, type SlackSkillOptions, SlacrawlClient, type SlacrawlOptions, } from "./skills/slack/index.js";
 export { SpotlightConnector, type SpotlightConnectorOptions, SpotlightSkill, type SpotlightSkillOptions, } from "./skills/spotlight/index.js";

package/dist/datasource/skills/factory.d.ts

@@ -11,6 +11,7 @@ import type { Embedder } from "../../embedding/embedder.js";
 import type { EmbeddingEndpointSource } from "../embedding-env.js";
 import type { DatasourceSkill } from "../types.js";
 import { type DiscrawlEmbeddingRuntime } from "./discrawl/index.js";
+import { type ObsidianMinSyncOptions } from "./obsidian/index.js";
 /** One configured datasource entry (the trusted `datasources.<name>` value). */
 export interface DatasourceSkillConfig {
     readonly enabled?: boolean;
@@ -46,6 +47,8 @@ export interface DatasourceEmbeddingOptions {
     readonly discrawl?: DiscrawlEmbeddingRuntime | (() => Promise<DiscrawlEmbeddingRuntime | undefined>);
     /** For CLIs that embed for themselves through env (mailcrawl, lazykatok): where the shared backend is. */
     readonly cliEndpoint?: EmbeddingEndpointSource;
+    /** MinSync binary, embedder and chunking shared with the local-file index; vault indexes run on it too. */
+    readonly minSync?: ObsidianMinSyncOptions;
 }
 /** Skill names this factory can build. */
 export declare const BUILTIN_DATASOURCE_SKILL_NAMES: readonly string[];

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

@@ -0,0 +1,83 @@
+/**
+ * HTTP client for a running Hister server (https://github.com/asciimoo/hister, AGPL-3.0).
+ *
+ * Hister is a separate program. AutoRAG never links, embeds, copies, or modifies its code: this file speaks
+ * Hister's public `GET /search` and `GET /api/config` JSON endpoints over HTTP, exactly like Hister's own
+ * `hister search` CLI. Hister owns its index, its browser-extension capture, its credentials, and its embeddings.
+ */
+export interface HisterClientOptions {
+    /** Hister server, default `http://127.0.0.1:4433`. */
+    readonly baseUrl?: string;
+    /** Name of the environment variable holding Hister's `app.access_token`. The token itself is never configured. */
+    readonly tokenEnv?: string;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+}
+export interface HisterHit {
+    readonly url: string;
+    readonly domain: string;
+    readonly title: string;
+    /** Highlighted-mark-free snippet (or the matched semantic chunk). */
+    readonly snippet: string;
+    readonly score: number;
+    /** Epoch ms of the last visit/update. */
+    readonly updatedAt: number | undefined;
+    readonly addedAt: number | undefined;
+    readonly language: string | undefined;
+    readonly description: string | undefined;
+}
+export type HisterFailureKind = "unavailable" | "auth" | "http" | "invalid-output" | "semantic-disabled";
+export interface HisterFailure {
+    readonly ok: false;
+    readonly kind: HisterFailureKind;
+    /** Verbatim: HTTP status and body, or the connection error. */
+    readonly message: string;
+}
+export type HisterResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | HisterFailure;
+export interface HisterSearchOptions {
+    readonly topK?: number;
+    readonly signal?: AbortSignal;
+    /** Restrict to one domain (exact match, Hister `domain:`). */
+    readonly domain?: string;
+}
+export declare class HisterClient {
+    readonly baseUrl: string;
+    private readonly tokenEnv;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly env;
+    constructor(options?: HisterClientOptions);
+    /** Lexical search over web pages only. */
+    searchLexical(query: string, options?: HisterSearchOptions): Promise<HisterResult<readonly HisterHit[]>>;
+    /**
+     * Semantic search. Hister embeds the query itself through the endpoint the operator configured on the server;
+     * AutoRAG sends only the question text. `semantic_hits` carry the matched chunk and similarity.
+     */
+    searchSemantic(query: string, options?: HisterSearchOptions): Promise<HisterResult<readonly HisterHit[]>>;
+    /** Count documents matching a Hister query. */
+    count(text: string, signal?: AbortSignal): Promise<HisterResult<number>>;
+    /** Reachability and authentication probe. Returns Hister's `/api/config` body. */
+    config(signal?: AbortSignal): Promise<HisterResult<Record<string, unknown>>>;
+    private search;
+    private request;
+}
+/**
+ * Wrap a free-text question as a Hister query confined to web pages.
+ *
+ * Hister ANDs bare terms, so a natural-language question would match almost nothing. Plain words become one
+ * alternation group `(a|b|c)`. That pipe is Hister's only OR: the word `OR` is not an operator there, it is searched
+ * as the literal English word, which matches most English pages. Hister's own syntax (quoted phrases,
+ * `field:value`, wildcards, negation) passes through untouched, and a query using any of it is sent with its plain
+ * words ANDed, exactly as written. A `sort:` directive is hoisted out of the group because Hister only honours it at
+ * the top level.
+ */
+export declare function buildWebQuery(question: string, domain?: string): string | undefined;
+/** Hister snippets carry `<mark>` highlights and HTML entities; the model reads plain text. */
+export declare function plainSnippet(snippet: string): string;
+/** Stable, opaque id for one page: the same URL always maps to the same chunk id. */
+export declare function pageId(url: string): string;
+export declare function isLoopback(hostname: string): boolean;

package/dist/datasource/skills/hister/embedding.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Sharing AutoRAG's embedding backend with Hister.
+ *
+ * Hister keeps its own vector store and embeds with whatever `semantic_search` in its config.yml names, so the
+ * only way the two can use one model is to copy the shared endpoint (the `minsync serve` daemon by default) into
+ * that block. Mismatched models are not an error anywhere: the vectors simply do not line up and results degrade
+ * silently. This module derives the block from {@link ResolvedEmbeddingEndpoint}, reads what Hister currently has,
+ * and rewrites only the six keys involved. Hister itself is never modified; its config.yml is its documented
+ * interface.
+ *
+ * `yaml` is a dev dependency of this package, so the file is edited line by line. Only the `semantic_search`
+ * block's own keys are touched and every other byte is preserved; the tests compare the result with a real YAML
+ * parser.
+ */
+import type { ResolvedEmbeddingEndpoint } from "../../embedding-env.js";
+/** The `semantic_search` keys that must agree with the shared embedding backend. */
+export interface HisterSemanticSettings {
+    readonly enable: boolean;
+    readonly embedding_endpoint: string;
+    readonly embedding_model: string;
+    readonly dimensions: number;
+    readonly query_prefix: string;
+    readonly document_prefix: string;
+}
+export type HisterSemanticKey = keyof HisterSemanticSettings;
+/**
+ * What Hister uses when its config does not say (v0.20.0 `config.go`): semantic search off, an Ollama endpoint, and
+ * a `query: ` prefix. Used only to report a missing key; the apply step always writes every key.
+ */
+export declare const HISTER_SEMANTIC_DEFAULTS: HisterSemanticSettings;
+export type DeriveResult = {
+    readonly ok: true;
+    readonly settings: HisterSemanticSettings;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * The settings that make Hister embed exactly like AutoRAG does. Refuses what Hister cannot do faithfully:
+ * - a TEI endpoint (Hister only calls the OpenAI `/v1/embeddings` route);
+ * - a remote endpoint (browsing text would leave the machine, and Hister's config would have to hold the key).
+ */
+export declare function deriveHisterSemanticSettings(endpoint: ResolvedEmbeddingEndpoint): DeriveResult;
+export declare function differingSemanticKeys(current: HisterSemanticSettings, wanted: HisterSemanticSettings): readonly HisterSemanticKey[];
+export declare function reindexRequired(changed: readonly HisterSemanticKey[]): boolean;
+export type ReadResult = {
+    readonly ok: true;
+    readonly settings: HisterSemanticSettings;
+    /** Keys the file sets itself; the rest are Hister's defaults. */
+    readonly explicit: readonly HisterSemanticKey[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function readHisterSemanticSettings(text: string): ReadResult;
+export type ApplyResult = {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** Set every {@link KEYS} entry inside `semantic_search`, creating the block when it is absent. */
+export declare function applyHisterSemanticSettings(text: string, settings: HisterSemanticSettings): ApplyResult;

package/dist/datasource/skills/hister/index.d.ts

@@ -0,0 +1,2 @@
+export { buildWebQuery, HisterClient, type HisterClientOptions, type HisterFailure, type HisterFailureKind, type HisterHit, type HisterResult, type HisterSearchOptions, pageId, } from "./client.js";
+export { HISTER_SKILL_TYPE, HisterSkill, type HisterSkillOptions } from "./skill.js";

package/dist/datasource/skills/hister/setup.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `autorag setup` support for the Hister datasource: is Hister installed and running, and does it embed with the
+ * same model as the rest of AutoRAG?
+ *
+ * Detection never writes anything. Writing Hister's config and restarting its service only happen when the operator
+ * passes `--sync-hister`, because that file and that login item belong to Hister and its operator. Hister is never
+ * modified; this only edits its documented config.yml, keeps a backup first, and restarts the service the same way
+ * the operator would.
+ */
+import type { ManagedEmbedder } from "../../../embedding/embedder.js";
+import { type HisterSemanticKey } from "./embedding.js";
+export interface HisterSetupEmbedding {
+    /** Hister's config already matches the shared embedding backend. */
+    readonly inSync: boolean;
+    /** `semantic_search` keys that differ from the shared backend, sorted. */
+    readonly differs: readonly HisterSemanticKey[];
+    /** Hister's config file was rewritten by this run. */
+    readonly applied: boolean;
+    /** Hister must be restarted to read the new config (it was not, or could not be). */
+    readonly restartRequired?: boolean;
+    /** Existing pages must be re-embedded (`hister reindex`) and that was not done. */
+    readonly reindexRequired?: boolean;
+    readonly reason?: string;
+}
+export interface HisterSetupReport {
+    readonly datasource: string;
+    readonly installed: boolean;
+    readonly running?: boolean;
+    readonly configPath?: string;
+    readonly embedding?: HisterSetupEmbedding;
+    readonly reason?: string;
+    /** What the operator (or an agent) should run next. */
+    readonly remediation?: string;
+}
+export interface HisterServiceDeps {
+    /** Hister's config.yml path, or undefined when it cannot be determined. */
+    readonly configPath?: () => string | undefined;
+    /** `GET /api/config` against the datasource's baseUrl. */
+    readonly health?: (baseUrl: string) => Promise<{
+        readonly reachable: boolean;
+        readonly semanticEnabled?: boolean;
+        readonly reason?: string;
+    }>;
+    /** Restart the Hister service. Omitted means the operator must do it. */
+    readonly restart?: () => Promise<{
+        readonly ok: boolean;
+        readonly reason?: string;
+    }>;
+    /** `hister reindex` against the running server. Omitted means the operator must do it. */
+    readonly reindex?: (baseUrl: string) => Promise<{
+        readonly ok: boolean;
+        readonly reason?: string;
+    }>;
+    readonly now?: () => number;
+    /** Pause between polls while a restarted server comes up. Tests replace it. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** How long to wait for a restarted server before giving up on the reindex. Default 30s. */
+    readonly waitMs?: number;
+}
+interface HisterEntry {
+    readonly name: string;
+    readonly baseUrl: string;
+    readonly semantic: boolean;
+    readonly tokenEnv?: string;
+}
+/** The first configured `hister` datasource (by template `type` or by name), with its connector options. */
+export declare function findHisterEntries(raw: Record<string, unknown>): readonly HisterEntry[];
+/** Where Hister reads its config on this platform, in the order Hister itself searches (docs/configuration). */
+export declare function defaultHisterConfigPath(env: NodeJS.ProcessEnv, exists?: (path: string) => boolean, platform?: NodeJS.Platform, home?: string): string | undefined;
+/** The real service deps. Restart is only offered where a service manager is known: Homebrew on macOS/Linux. */
+export declare function systemHisterDeps(env: NodeJS.ProcessEnv, hister: string | undefined): HisterServiceDeps;
+/**
+ * Probe Hister for every configured `hister` datasource. Writes only when `sync` is true, and then only Hister's own
+ * config.yml (after a backup), followed by the service restart and reindex the change needs.
+ */
+export declare function setupHister(options: {
+    readonly entries: readonly HisterEntry[];
+    readonly embedder: ManagedEmbedder;
+    readonly executable: (name: string) => string | undefined;
+    readonly deps: HisterServiceDeps;
+    readonly sync: boolean;
+    readonly assertLockOwned?: () => void;
+}): Promise<{
+    readonly reports: readonly HisterSetupReport[];
+    readonly changed: boolean;
+}>;
+export {};

package/dist/datasource/skills/hister/skill.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Browser web-history datasource backed by a running Hister server.
+ *
+ * Hister (https://github.com/asciimoo/hister, AGPL-3.0-or-later) is a separate program. It captures the pages a
+ * Chromium or Firefox browser visits (through its own extension), keeps the full text, and owns the lexical and
+ * semantic indexes, incremental updates, and credentials. AutoRAG only sends search requests to its public HTTP
+ * API and maps the answers. It does not link, embed, bundle, copy, or modify Hister, and never hides that Hister
+ * is the backend: the manifest names it, its license, and its source.
+ *
+ * Web pages only: every query is confined to `type:web`, and any document Hister reports with another type
+ * (watched local files, remote file snapshots) is dropped. Local directory indexing in Hister is never used.
+ */
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceIndexOptions, DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { HisterClient, type HisterClientOptions } from "./client.js";
+export declare const HISTER_SKILL_TYPE = "hister-web-history";
+export interface HisterSkillOptions extends HisterClientOptions {
+    readonly client?: HisterClient;
+    readonly datasourceId?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly tags?: readonly string[];
+    /**
+     * Also register Hister's semantic search. Requires `semantic_search.enable` and an embedding endpoint in the
+     * Hister server config; Hister embeds the query text through the endpoint the operator chose there.
+     */
+    readonly semantic?: boolean;
+}
+type Mode = "lexical" | "semantic";
+export declare class HisterSkill implements DatasourceSkill {
+    private readonly datasourceId;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private readonly semantic;
+    private readonly client;
+    /** A bad `baseUrl` or token setup is reported through `index()`/search, never thrown out of config loading. */
+    private readonly configError;
+    private lastIndexedAt;
+    private lastError;
+    constructor(options?: HisterSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    /**
+     * Hister indexes pages itself the moment the browser extension sends them, so there is nothing to copy.
+     * `index()` is a read-only probe: reachability, authentication, how many web pages are searchable, and whether
+     * Hister also holds non-web documents that this datasource will never return.
+     */
+    index(options?: DatasourceIndexOptions): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    search(mode: Mode, query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    /** Opaque, stable identity: `/<id>/<instance>/pages/<domain>/<hash of the URL>`. */
+    private sourceFor;
+    private toResult;
+    /** Does the scope reach this datasource at all, and can it be pushed down to Hister as `domain:`? */
+    private scopeTarget;
+    private failFrom;
+    private fail;
+    private note;
+}
+export {};

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

@@ -1,6 +1,4 @@
-export { QmdClient } from "./client.js";
-export { ObsidianBm25Method, type ObsidianMethodOptions, type ObsidianSearchClient, ObsidianSemanticMethod, } from "./methods.js";
-export { obsidianDatasourceRoot, obsidianQmdCacheDir, obsidianQmdConfigDir, obsidianSourcePath, parseObsidianSourcePath, stripEdgeDashes, toQmdCollectionName, } from "./paths.js";
-export { ObsidianSkill, type ObsidianSkillClient, type ObsidianSkillOptions } from "./skill.js";
-export type { QmdEmbedResult, QmdEnsureResult, QmdFailureReason, QmdOptions, QmdSearchHit, QmdSearchMode, QmdSearchOptions, QmdSearchResult, QmdUpdateResult, } from "./types.js";
-export { DEFAULT_QMD_BINARY, DEFAULT_QMD_MAX_BUFFER_BYTES, DEFAULT_QMD_TIMEOUT_MS, } from "./types.js";
+export { ObsidianBm25Method, type ObsidianMethodOptions, ObsidianSemanticMethod } from "./methods.js";
+export { encodeSourceSegment, obsidianDatasourceDir, obsidianInstanceSource, obsidianMinSyncWorkspace, obsidianNoteSource, } from "./paths.js";
+export { ObsidianSkill, type ObsidianSkillOptions } from "./skill.js";
+export type { ObsidianMinSyncOptions, ObsidianSearchMode } from "./vault-index.js";

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

@@ -1,26 +1,22 @@
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
-import type { QmdSearchMode, QmdSearchOptions, QmdSearchResult } from "./types.js";
-export interface ObsidianSearchClient {
-    search(mode: QmdSearchMode, query: string, options?: QmdSearchOptions): Promise<QmdSearchResult>;
-}
+import type { ObsidianSearchMode, ObsidianVaultIndex } from "./vault-index.js";
 export interface ObsidianMethodOptions {
-    readonly client: ObsidianSearchClient;
-    readonly instanceId: string;
-    readonly tags?: readonly string[];
+    readonly index: ObsidianVaultIndex;
+    readonly tags: readonly string[];
 }
-export declare class ObsidianBm25Method implements RetrievalMethod {
-    private readonly client;
-    private readonly instanceId;
+/** One MinSync query mode over one vault. A failure reaches the pipeline verbatim and is reported as unsearched. */
+declare class ObsidianMinSyncMethod implements RetrievalMethod {
+    private readonly index;
     private readonly tags;
-    constructor(options: ObsidianMethodOptions);
+    private readonly mode;
+    constructor(mode: ObsidianSearchMode, options: ObsidianMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
-export declare class ObsidianSemanticMethod implements RetrievalMethod {
-    private readonly client;
-    private readonly instanceId;
-    private readonly tags;
+export declare class ObsidianBm25Method extends ObsidianMinSyncMethod {
+    constructor(options: ObsidianMethodOptions);
+}
+export declare class ObsidianSemanticMethod extends ObsidianMinSyncMethod {
     constructor(options: ObsidianMethodOptions);
-    describe(): RetrievalMethodDescriptor;
-    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
+export {};

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

@@ -1,27 +1,27 @@
 /**
- * Path helpers for the Obsidian (`qmd`) datasource skill.
+ * Path helpers for the Obsidian datasource.
  *
- * All AutoRAG-managed state lives under
- * `<workspaceRoot>/.autorag/datasources/obsidian/<instanceId>/`. The external
- * `qmd` CLI is pointed at isolated config/cache dirs so multiple workspaces
- * never share an index. Callers surface opaque slash-hierarchical sources of
- * the form `/obsidian/<instance-id>/chunks/<chunk-id>`.
+ * Everything AutoRAG owns for one vault lives under
+ * `<workspaceRoot>/.autorag/datasources/obsidian/<instance>/`: a MinSync workspace of its own
+ * (`minsync/`, never shared with the local-file index) and the staging record (`staging.json`)
+ * that maps staged notes back to the vault. Callers see slash-hierarchical opaque sources of
+ * the form `/obsidian/<instance>/<vault-relative note path>`.
  */
-export declare const AUTORAG_DIRNAME = ".autorag";
-export declare const DATASOURCES_DIRNAME = "datasources";
-export declare const OBSIDIAN_DATASOURCE_DIRNAME = "obsidian";
-export declare const OBSIDIAN_SOURCE_KIND: "obsidian";
-export declare function obsidianDatasourceRoot(workspaceRoot: string, instanceId: string): string;
-/** Directory passed to `QMD_CONFIG_DIR` (holds `index.yml`). */
-export declare function obsidianQmdConfigDir(workspaceRoot: string, instanceId: string): string;
-/** Directory passed to `XDG_CACHE_HOME` (holds `qmd/index.sqlite`). */
-export declare function obsidianQmdCacheDir(workspaceRoot: string, instanceId: string): string;
-export declare function obsidianSourcePath(instanceId: string, chunkId: string): string;
-export declare function parseObsidianSourcePath(source: string): {
-    readonly instanceId: string;
-    readonly chunkId: string;
-} | undefined;
-/** Strip leading and trailing ASCII dashes without a quadratic regex. */
-export declare function stripEdgeDashes(value: string): string;
-/** Sanitize an instance id into a qmd collection name. */
-export declare function toQmdCollectionName(instanceId: string): string;
+export declare const OBSIDIAN_DATASOURCE_ID = "obsidian";
+export declare const OBSIDIAN_SKILL_TYPE = "obsidian-vault";
+export declare function obsidianDatasourceDir(workspaceRoot: string, instanceId: string): string;
+/** The MinSync workspace this vault is indexed in; staged notes live in its `files/` folder. */
+export declare function obsidianMinSyncWorkspace(workspaceRoot: string, instanceId: string): string;
+/** Kept beside the MinSync workspace, outside the tree MinSync indexes. */
+export declare function obsidianStagingStatePath(workspaceRoot: string, instanceId: string): string;
+/**
+ * Escape what would change the meaning of a source segment: `%` (the escape itself), `/` (the
+ * separator, possible in an instance id), `#` (datasource sources never carry a fragment), `\`
+ * (not valid in a virtual path) and `*` (a scope glob). Everything else, spaces and non-Latin
+ * letters included, stays readable.
+ */
+export declare function encodeSourceSegment(segment: string): string;
+/** The root source of one vault: the scope that selects every note in it. */
+export declare function obsidianInstanceSource(instanceId: string): string;
+/** The source of one note, from its vault-relative path written with `/` separators. */
+export declare function obsidianNoteSource(instanceId: string, relativePath: string): string;

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

@@ -1,37 +1,33 @@
 import type { RetrievalMethod } from "../../../retrieval/types.js";
 import type { DatasourceIndexOptions, DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
-import { type ObsidianSearchClient } from "./methods.js";
-import type { QmdEmbedResult, QmdEnsureResult, QmdUpdateResult } from "./types.js";
-export interface ObsidianSkillClient extends ObsidianSearchClient {
-    ensureCollection(signal?: AbortSignal): Promise<QmdEnsureResult>;
-    update(signal?: AbortSignal): Promise<QmdUpdateResult>;
-    embed(signal?: AbortSignal): Promise<QmdEmbedResult>;
-}
+import { type ObsidianMinSyncOptions } from "./vault-index.js";
 export interface ObsidianSkillOptions {
     readonly datasourceId?: string;
-    readonly client?: ObsidianSkillClient;
     readonly vaultPath?: string;
-    readonly binaryPath?: string;
     readonly instanceId?: string;
     readonly instances?: readonly string[];
     readonly pollingIntervalMs?: number;
     readonly tags?: readonly string[];
     readonly lastIndexedAt?: number;
+    /** Where `.autorag/datasources/obsidian/<instance>` is kept. Required to index or search. */
     readonly workspaceRoot?: string;
-    readonly collectionName?: string;
-    readonly timeoutMs?: number;
-    readonly configPath?: string;
+    /** The install's MinSync binary, embedder and chunking, shared with the local-file index. */
+    readonly minSync?: ObsidianMinSyncOptions;
     readonly connectorOptions?: {
         readonly vaultPath?: string;
     };
 }
+/**
+ * An Obsidian vault as a datasource: its markdown notes are indexed by MinSync (BM25 and
+ * semantic) in a workspace of their own, and a note's source is its vault-relative path, so a
+ * folder is an ordinary `scope`.
+ */
 export declare class ObsidianSkill implements DatasourceSkill {
-    private readonly client;
+    private readonly vaultIndex;
     private readonly instanceId;
     private readonly instances;
     private readonly pollingIntervalMs;
     private readonly tags;
-    private readonly vaultPath;
     private lastIndexedAt;
     private lastError;
     constructor(options?: ObsidianSkillOptions);
@@ -41,5 +37,4 @@ export declare class ObsidianSkill implements DatasourceSkill {
     retrievalMethods(): readonly RetrievalMethod[];
     describeSources(): readonly SourceDescription[];
     skillManifest(): DatasourceSkillManifest;
-    private fail;
 }

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

@@ -0,0 +1,50 @@
+export interface VaultNote {
+    /** Vault-relative path, NFC-normalized, `/`-separated. */
+    readonly relativePath: string;
+    readonly sourcePath: string;
+    readonly size: number;
+    /** Exact nanosecond mtime as a decimal string (it exceeds a double's integer range). */
+    readonly mtimeNs: string;
+}
+export interface VaultListing {
+    readonly notes: ReadonlyMap<string, VaultNote>;
+    /** Folders (vault-relative) that could not be read; their staged notes are kept as they were. */
+    readonly unreadableFolders: readonly string[];
+    /** Notes dropped because another note has the same NFC-normalized path. */
+    readonly collisions: readonly string[];
+}
+export declare class VaultUnavailableError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/**
+ * List the vault's notes. Dot-prefixed folders and files (`.obsidian`, `.trash`, `.git`),
+ * `node_modules`, and symlinks are not part of the vault's knowledge and are skipped.
+ * Throws {@link VaultUnavailableError} when the vault root itself cannot be read.
+ */
+export declare function listVaultNotes(vaultPath: string): Promise<VaultListing>;
+interface StagingEntry {
+    readonly sourcePath: string;
+    readonly size: number;
+    readonly mtimeNs: string;
+}
+export interface StagingState {
+    readonly version: 1;
+    readonly entries: Readonly<Record<string, StagingEntry>>;
+}
+export declare function loadStagingState(statePath: string): StagingState;
+export interface StageResult {
+    readonly staged: number;
+    readonly copied: number;
+    readonly removed: number;
+    /** Notes that could not be copied this time; an earlier staged copy, if any, was kept. */
+    readonly failed: readonly string[];
+}
+/**
+ * Bring `<filesRoot>` in line with the vault: copy new and changed notes, delete notes that no
+ * longer exist, and leave notes under an unreadable folder exactly as they were.
+ */
+export declare function stageNotes(filesRoot: string, statePath: string, listing: VaultListing, options?: {
+    readonly force?: boolean;
+}): StageResult;
+export {};

package/dist/datasource/skills/obsidian/vault-index.d.ts

@@ -0,0 +1,44 @@
+import type { MinSyncVectorMethodOptions } from "../../../minsync/method.js";
+import type { RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceDiagnostic, DatasourceDiagnosticCode } from "../../types.js";
+/** The MinSync settings a vault shares with the rest of the install: binary, embedder, chunking. */
+export type ObsidianMinSyncOptions = Pick<MinSyncVectorMethodOptions, "binaryPath" | "autoInstall" | "installer" | "embedder" | "maxChunkSize">;
+export interface ObsidianVaultIndexOptions {
+    readonly instanceId: string;
+    readonly vaultPath: string | undefined;
+    readonly workspaceRoot: string | undefined;
+    readonly minSync?: ObsidianMinSyncOptions;
+}
+export type ObsidianSearchMode = "bm25" | "semantic";
+export interface ObsidianSearchOptions {
+    readonly topK?: number;
+    readonly scope?: string;
+    readonly signal?: AbortSignal;
+}
+export type VaultSyncOutcome = {
+    readonly ok: true;
+    readonly notes: number;
+    readonly diagnostics: readonly DatasourceDiagnostic[];
+} | {
+    readonly ok: false;
+    readonly code: DatasourceDiagnosticCode;
+    readonly message: string;
+};
+/**
+ * One vault, indexed by MinSync in a workspace of its own. Notes are staged under the workspace's
+ * `files/` folder (see `staging.ts`), `minsync sync` embeds and indexes them incrementally, and a
+ * query runs against that index and maps each chunk back to its note.
+ */
+export declare class ObsidianVaultIndex {
+    private readonly instanceId;
+    private readonly vaultPath;
+    private readonly workspaceRoot;
+    private readonly minSync;
+    constructor(options: ObsidianVaultIndexOptions);
+    /** Mirror the vault's notes into the MinSync workspace and sync it. Never throws except on abort. */
+    sync(signal?: AbortSignal): Promise<VaultSyncOutcome>;
+    private syncLocked;
+    /** Search the indexed vault. Rejects, with the reason, when the vault was never indexed or a sync is running. */
+    query(mode: ObsidianSearchMode, text: string, options?: ObsidianSearchOptions): Promise<RetrievalResult[]>;
+    private queryLocked;
+}