@autorag/librarian 2.5.1 → 2.5.3

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

@@ -42,6 +42,12 @@ export interface ConnectorSkillDefinition {
     readonly manifestDescription: string;
     /** Extra path-opaque manifest body lines (after the standard sections). */
     readonly manifestNotes?: readonly string[];
+    /**
+     * Native CLI note for the manifest, e.g. how to inspect the underlying
+     * tool directly. Omit when the connector has no external CLI; the manifest
+     * then states that the dedicated search tool is the only search path.
+     */
+    readonly nativeCliNote?: string;
 }
 export interface ConnectorSkillOptions {
     readonly connector: DatasourceConnector;

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

@@ -13,6 +13,8 @@ export interface CrawlerDatasourceDefinition {
     readonly contentType: string;
     readonly manifestDescription: string;
     readonly backendName: string;
+    /** One copy-pastable native CLI search example shown in the skill manifest. */
+    readonly nativeCliSearchExample: string;
 }
 export interface CrawlerDatasourceSkillOptions {
     readonly client: CrawlerSkillClient;

package/dist/datasource/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Datasource retrieval errors.
+ *
+ * A CLI-backed datasource that cannot answer must say why. Its retrieval method
+ * throws this error instead of returning an empty result set, so the retrieval
+ * 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, …). */
+export interface DatasourceCliFailure {
+    readonly reason: string;
+    readonly stderr?: string;
+    readonly stdout?: string;
+    readonly code?: number | null;
+}
+/** Error thrown by a datasource retrieval method when its CLI failed. */
+export declare class DatasourceCliError extends Error {
+    readonly datasourceId: string;
+    readonly command: string;
+    readonly reason: string;
+    readonly stderr: string;
+    readonly code: number | null;
+    constructor(datasourceId: string, command: string, failure: DatasourceCliFailure);
+}
+/** Build the error a datasource retrieval method throws for a failed CLI call. */
+export declare function datasourceCliError(datasourceId: string, command: string, failure: DatasourceCliFailure): DatasourceCliError;

package/dist/datasource/index.d.ts

@@ -12,8 +12,9 @@ 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 type { KatokFailureReason, KatokHit, KatokOptions, KatokSearchMode, KatokSearchOptions, KatokSearchResult, KatokSkillClient, KatokSkillOptions, } from "./skills/katok/index.js";
-export { KatokBm25Method, KatokClient, KatokSemanticMethod, KatokSkill, } from "./skills/katok/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";

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

@@ -26,7 +26,7 @@ export interface DiscrawlSkillOptions {
 /**
  * Discord datasource skill backed by the external `discrawl` CLI.
  *
- * Mirrors the katok model: the CLI owns the archive, the FTS5 index, and the
+ * Mirrors the lazykatok model: the CLI owns the archive, the FTS5 index, and the
  * vector index; AutoRAG only spawns it and maps results. AutoRAG never calls
  * the Discord API itself and never reads the Discord Desktop cache directly.
  *

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

@@ -24,14 +24,14 @@ export declare const ENGLISH_ONLY_EMBEDDING_MODELS: ReadonlySet<string>;
  * Default embedding model AutoRAG configures for workspace-managed discrawl
  * configs. `embeddinggemma`
  * (Gemma 3 300M, 768 dimensions) covers 100+ languages and matches the
- * EmbeddingGemma embedder katok uses for KakaoTalk, so every CLI-backed
+ * EmbeddingGemma embedder lazykatok uses for KakaoTalk, so every CLI-backed
  * datasource shares one local embedding model (served through Ollama).
  */
 export declare const DEFAULT_DISCRAWL_EMBEDDING_MODEL = "embeddinggemma";
 export declare const DEFAULT_DISCRAWL_EMBEDDING_PROVIDER = "ollama";
 /**
  * Configuration for the discrawl client. All fields optional; defaults mirror
- * the katok client. The client spawns the `discrawl` binary as a child process
+ * the lazykatok client. The client spawns the `discrawl` binary as a child process
  * — it never opens the Discord archive database directly.
  *
  * AutoRAG drives discrawl's local archive only: `wiretap` to import the

package/dist/datasource/skills/github-gist/connector.d.ts

@@ -0,0 +1,38 @@
+/**
+ * GitHub Gist connector (issue #1588).
+ *
+ * Indexes the authenticated account's gists (public + secret, bounded by the
+ * token's scopes) through the GitHub REST API. Incremental: the gist list
+ * endpoint returns `id` + `updated_at` cheaply, so a persisted cursor map
+ * (`state.json`) decides which gists need a full content fetch and which
+ * disappeared (reported via `deletedDocIds`). Token resolution order:
+ * explicit `token` > `tokenEnv` (default `GITHUB_TOKEN`) > `gh auth token`
+ * when the gh CLI fallback is enabled. Never throws.
+ */
+import type { ConnectorFetchResult, DatasourceConnector } from "../../connector.js";
+export interface GitHubGistConnectorOptions {
+    /** GitHub REST base; override to point at a mock server in tests. */
+    readonly baseUrl?: string;
+    /** Personal access token; explicit value wins over {@link tokenEnv}. */
+    readonly token?: string;
+    /** Env var name holding the token. Default `GITHUB_TOKEN`. */
+    readonly tokenEnv?: string;
+    /** When true (default), fall back to `gh auth token` for auth. */
+    readonly ghCliFallback?: boolean;
+    /** Injectable gh-token resolver (tests); defaults to spawning `gh auth token`. */
+    readonly ghTokenRunner?: () => Promise<string | undefined>;
+    readonly timeoutMs?: number;
+    readonly fetchImpl?: typeof fetch;
+    /** Persisted incremental cursor; omitted ⇒ every fetch is a full sync. */
+    readonly statePath?: string;
+    readonly maxPages?: number;
+    readonly maxGists?: number;
+}
+export declare class GitHubGistConnector implements DatasourceConnector {
+    private readonly options;
+    constructor(options?: GitHubGistConnectorOptions);
+    fetch(signal?: AbortSignal): Promise<ConnectorFetchResult>;
+    private resolveAuth;
+    private loadState;
+    private saveState;
+}

package/dist/datasource/skills/github-gist/index.d.ts

@@ -0,0 +1,3 @@
+export { GitHubGistConnector, type GitHubGistConnectorOptions } from "./connector.js";
+export { createGatewayGistEmbedder, type GatewayGistEmbedderOptions, type GistEmbedder, type GistEmbeddingIdentity, GistSemanticIndex, GitHubGistSemanticMethod, } from "./semantic.js";
+export { GITHUB_GIST_SKILL_DEFINITION, type GitHubGistSemanticOptions, GitHubGistSkill, type GitHubGistSkillOptions, gistDatasourceDir, } from "./skill.js";

package/dist/datasource/skills/github-gist/semantic.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Semantic retrieval for the github-gist datasource (issue #1588).
+ *
+ * A small persisted vector sidecar (`vectors.json`) mirrors the chunk store:
+ * entries are keyed by chunk id with a content hash so unchanged chunks are
+ * never re-embedded, removed chunks are pruned, and an embedding-identity
+ * change (provider/model/dimension) forces a full re-embed. The default
+ * embedder talks to the loopback autorag-gateway (`ensureRuntime` with
+ * `cachedOnly`, then `POST /v1/embeddings`); tests inject a stub. Every
+ * failure degrades — indexing stays lexical-only and retrieval returns [].
+ */
+import type { ProfileId } from "../../../embedding-runtime/types.js";
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceChunkStore, StoredChunk } from "../../chunk-store.js";
+export interface GistEmbeddingIdentity {
+    readonly provider: string;
+    readonly model: string;
+    readonly dimension: number;
+}
+/** Embedder contract: identity is async because the gateway resolves it lazily. */
+export interface GistEmbedder {
+    identity(): Promise<GistEmbeddingIdentity>;
+    embed(texts: readonly string[]): Promise<readonly (readonly number[])[]>;
+}
+export interface GistSemanticSyncOk {
+    readonly ok: true;
+    /** Number of chunks (re-)embedded in this sync. */
+    readonly embedded: number;
+}
+export interface GistSemanticSyncFail {
+    readonly ok: false;
+    readonly message: string;
+}
+/** Persisted per-instance vector sidecar mirroring the chunk store. */
+export declare class GistSemanticIndex {
+    private readonly statePath;
+    private identity;
+    private entries;
+    private loaded;
+    constructor(options?: {
+        readonly statePath?: string;
+    });
+    /**
+     * Embed new/changed chunks, prune removed ones, and persist. Never throws;
+     * an embedder failure leaves prior entries intact and reports ok:false.
+     */
+    sync(chunks: readonly StoredChunk[], embedder: GistEmbedder): Promise<GistSemanticSyncOk | GistSemanticSyncFail>;
+    /** Cosine-ranked chunk ids for a query vector. Never throws. */
+    searchByVector(queryVector: readonly number[], topK: number): readonly {
+        chunkId: string;
+        score: number;
+    }[];
+    private ensureLoaded;
+    private persist;
+}
+export interface GitHubGistSemanticMethodOptions {
+    readonly skillName: string;
+    readonly skillType: string;
+    readonly instanceId: string;
+    readonly tags: readonly string[];
+    readonly store: DatasourceChunkStore;
+    readonly index: GistSemanticIndex;
+    readonly embedder: GistEmbedder;
+}
+/** Cosine similarity retrieval over the gist vector sidecar. Never throws. */
+export declare class GitHubGistSemanticMethod implements RetrievalMethod {
+    private readonly options;
+    constructor(options: GitHubGistSemanticMethodOptions);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    private matchesScope;
+}
+export interface GatewayGistEmbedderOptions {
+    /** Runtime resolver; defaults to the shared embedding-runtime ensureRuntime. */
+    readonly runtime?: {
+        ensureRuntime(input?: {
+            profileId?: ProfileId;
+            cachedOnly?: boolean;
+        }): Promise<{
+            baseUrl: string;
+            identity: {
+                provider: string;
+                model: string;
+                dimension: number;
+            };
+        }>;
+    };
+    readonly profileId?: ProfileId;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Production embedder backed by the loopback autorag-gateway. The runtime is
+ * ensured lazily with `cachedOnly` so semantic retrieval never triggers a
+ * model download; an unprimed cache surfaces as a sync/retrieve degrade.
+ */
+/**
+ * Texts per `/v1/embeddings` call. The llama.cpp upstream rejects very large
+ * batches (HTTP 413 on a full-archive sync), so embedding fans out in
+ * bounded sequential batches while preserving input order.
+ */
+export declare const GIST_EMBED_BATCH_SIZE = 32;
+export declare function createGatewayGistEmbedder(options?: GatewayGistEmbedderOptions): GistEmbedder;

package/dist/datasource/skills/github-gist/skill.d.ts

@@ -0,0 +1,39 @@
+/**
+ * GitHub Gist datasource skill (issue #1588).
+ *
+ * Composition: {@link GitHubGistConnector} incrementally mirrors the
+ * authenticated account's gists into the shared chunk store (lexical BM25),
+ * and a {@link GistSemanticIndex} vector sidecar adds semantic retrieval
+ * through the loopback embedding gateway. Embedding failures degrade to a
+ * `semantic-unavailable` warning — indexing and lexical retrieval continue.
+ */
+import type { RetrievalMethod } from "../../../retrieval/types.js";
+import { ConnectorDatasourceSkill, type ConnectorSkillDefinition, type ConnectorSkillOptions } from "../../connector-skill.js";
+import type { DatasourceIndexResult } from "../../types.js";
+import { GitHubGistConnector, type GitHubGistConnectorOptions } from "./connector.js";
+import { type GatewayGistEmbedderOptions, type GistEmbedder } from "./semantic.js";
+export declare const GITHUB_GIST_SKILL_DEFINITION: ConnectorSkillDefinition;
+export declare function gistDatasourceDir(workspaceRoot: string, skillName: string, instanceId: string): string;
+export interface GitHubGistSemanticOptions {
+    /** Set false to run lexical-only. Default true. */
+    readonly enabled?: boolean;
+    /** Injected embedder (tests); defaults to the loopback gateway embedder. */
+    readonly embedder?: GistEmbedder;
+    readonly embedderOptions?: GatewayGistEmbedderOptions;
+    /** Vector sidecar path override; defaults under `.autorag/datasources/…`. */
+    readonly statePath?: string;
+}
+export interface GitHubGistSkillOptions extends Omit<ConnectorSkillOptions, "connector"> {
+    /** Trusted connector configuration; a pre-built connector wins. */
+    readonly connector?: GitHubGistConnector;
+    readonly connectorOptions?: GitHubGistConnectorOptions;
+    readonly semantic?: GitHubGistSemanticOptions;
+}
+export declare class GitHubGistSkill extends ConnectorDatasourceSkill {
+    private readonly semanticIndex;
+    private readonly semanticEmbedder;
+    private readonly semanticMethod;
+    constructor(options?: GitHubGistSkillOptions);
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+}

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

@@ -0,0 +1,23 @@
+import { CrawlerCliClient } from "../../crawler-client.js";
+import type { CrawlerSearchResult } from "../../crawler-types.js";
+export interface LarkClientOptions {
+    readonly binaryPath?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly timeoutMs?: number;
+    readonly chatIds?: readonly string[];
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export declare class LarkClient {
+    private readonly version;
+    private readonly auth;
+    private readonly messages;
+    private readonly docs;
+    private readonly sleep;
+    constructor(options?: LarkClientOptions);
+    probeVersion(): Promise<CrawlerSearchResult | Awaited<ReturnType<CrawlerCliClient["sync"]>>>;
+    probeAuth(): Promise<Awaited<ReturnType<CrawlerCliClient["sync"]>>>;
+    searchMessages(query: string, topK: number | undefined): Promise<CrawlerSearchResult>;
+    searchDocs(query: string, topK: number | undefined): Promise<CrawlerSearchResult>;
+    private retry;
+}
+export declare function isSafeId(value: string): boolean;

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

@@ -0,0 +1,2 @@
+export { isSafeId, LarkClient, type LarkClientOptions } from "./client.js";
+export { LarkSkill, type LarkSkillOptions } from "./skill.js";

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

@@ -0,0 +1,36 @@
+import type { RetrievalMethod, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
+import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
+import { LarkClient, type LarkClientOptions } from "./client.js";
+export interface LarkSkillOptions extends LarkClientOptions {
+    readonly client?: LarkClient;
+    readonly datasourceId?: string;
+    readonly instanceId?: string;
+    readonly instances?: readonly string[];
+    readonly tags?: readonly string[];
+    readonly embedderBaseUrl?: string;
+}
+type Surface = "messages" | "docs";
+export declare class LarkSkill implements DatasourceSkill {
+    private readonly client;
+    private readonly datasourceId;
+    private readonly instanceId;
+    private readonly instances;
+    private readonly tags;
+    private readonly chatIds;
+    private readonly embedderBaseUrl;
+    private lastIndexedAt;
+    private lastError;
+    constructor(options?: LarkSkillOptions);
+    describe(): DatasourceSkillDescriptor;
+    polling(): PollingMetadata;
+    index(): Promise<DatasourceIndexResult>;
+    retrievalMethods(): readonly RetrievalMethod[];
+    describeSources(): readonly SourceDescription[];
+    skillManifest(): DatasourceSkillManifest;
+    search(surface: Surface, query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+    methodTags(surface: Surface): readonly string[];
+    private ok;
+    private fail;
+    private note;
+}
+export {};

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

@@ -0,0 +1,28 @@
+import type { LazykatokChunkResult, LazykatokContextResult, LazykatokDoctorResult, LazykatokIndexResult, LazykatokOptions, LazykatokParentResult, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSyncResult } from "./types.js";
+/**
+ * Thin external `lazykatok` CLI wrapper. Every method spawns the `lazykatok` binary as
+ * a child process, parses JSON from stdout, and returns a discriminated ok/fail
+ * union. No method throws for expected failures (missing binary, CLI nonzero
+ * exit, timeout, oversized output, or invalid JSON). The client never opens the
+ * KakaoTalk database directly.
+ */
+export declare class LazykatokClient {
+    private readonly options;
+    constructor(options?: LazykatokOptions);
+    doctor(signal?: AbortSignal): Promise<LazykatokDoctorResult>;
+    sync(signal?: AbortSignal): Promise<LazykatokSyncResult>;
+    index(signal?: AbortSignal): Promise<LazykatokIndexResult>;
+    search(mode: LazykatokSearchMode, query: string, options?: LazykatokSearchOptions): Promise<LazykatokSearchResult>;
+    chunkGet(chunkId: string, signal?: AbortSignal): Promise<LazykatokChunkResult>;
+    context(chunkId: string, signal?: AbortSignal): Promise<LazykatokContextResult>;
+    parent(chunkId: string, signal?: AbortSignal): Promise<LazykatokParentResult>;
+    /** Single retrieval pipeline: build env, spawn, parse-free raw result. */
+    private run;
+}
+/**
+ * `sync` argv for the configured source adapter. A bare `sync --json` makes the CLI
+ * fall back to its config file, whose default adapter is `fixture` and fails with
+ * "fixture source requires a JSONL path", so the live macOS adapter is named
+ * explicitly on darwin while other platforms defer to the CLI's own config.
+ */
+export declare function syncArgs(options: LazykatokOptions, platform?: NodeJS.Platform): readonly string[];

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

@@ -0,0 +1,12 @@
+/**
+ * KakaoTalk datasource skill barrel.
+ *
+ * Re-exports the retrieval methods and skill plus the underlying client/types
+ * from sibling modules. Public source paths are path-opaque virtual paths of
+ * the form `/kakao/<instance-id>/chunks/<chunk-id>`.
+ */
+export { LazykatokClient } from "./client.js";
+export { LazykatokBm25Method, type LazykatokMethodOptions, type LazykatokSearchClient, LazykatokSemanticMethod, } from "./methods.js";
+export { LazykatokSkill, type LazykatokSkillClient, type LazykatokSkillOptions } from "./skill.js";
+export type { LazykatokChunkResult, LazykatokDoctorResult, LazykatokFailureReason, LazykatokHit, LazykatokIndexResult, LazykatokOptions, LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult, LazykatokSyncResult, } from "./types.js";
+export { DEFAULT_LAZYKATOK_OPTIONS } from "./types.js";

package/dist/datasource/skills/{katok → lazykatok}/methods.d.ts

@@ -1,42 +1,42 @@
 import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "../../../retrieval/types.js";
-import type { KatokSearchMode, KatokSearchOptions, KatokSearchResult } from "./types.js";
+import type { LazykatokSearchMode, LazykatokSearchOptions, LazykatokSearchResult } from "./types.js";
 /**
  * Narrow client surface required by the KakaoTalk retrieval methods.
- * The real {@link KatokClient} satisfies this structurally; tests may stub it.
+ * The real {@link LazykatokClient} satisfies this structurally; tests may stub it.
  */
-export interface KatokSearchClient {
-    search(mode: KatokSearchMode, query: string, options?: KatokSearchOptions): Promise<KatokSearchResult>;
+export interface LazykatokSearchClient {
+    search(mode: LazykatokSearchMode, query: string, options?: LazykatokSearchOptions): Promise<LazykatokSearchResult>;
 }
-export interface KatokMethodOptions {
-    readonly client: KatokSearchClient;
+export interface LazykatokMethodOptions {
+    readonly client: LazykatokSearchClient;
     readonly instanceId: string;
     readonly tags?: readonly string[];
 }
 /**
  * Lexical (BM25) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in keyword mode. Katok does not expose source scopes; access is
+ * `lazykatok` CLI in keyword mode. Lazykatok does not expose source scopes; access is
  * controlled at the datasource/tag level. All client failures collapse to an
  * empty result set; retrieval never throws.
  */
-export declare class KatokBm25Method implements RetrievalMethod {
+export declare class LazykatokBm25Method implements RetrievalMethod {
     private readonly client;
     private readonly instanceId;
     private readonly tags;
-    constructor(options: KatokMethodOptions);
+    constructor(options: LazykatokMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }
 /**
  * Semantic (vector) retrieval over a KakaoTalk datasource via the external
- * `katok` CLI in semantic mode. Katok does not expose source scopes; access is
+ * `lazykatok` CLI in semantic mode. Lazykatok does not expose source scopes; access is
  * controlled at the datasource/tag level. All client failures collapse to an
  * empty result set; retrieval never throws.
  */
-export declare class KatokSemanticMethod implements RetrievalMethod {
+export declare class LazykatokSemanticMethod implements RetrievalMethod {
     private readonly client;
     private readonly instanceId;
     private readonly tags;
-    constructor(options: KatokMethodOptions);
+    constructor(options: LazykatokMethodOptions);
     describe(): RetrievalMethodDescriptor;
     retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
 }

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

@@ -0,0 +1,40 @@
+/**
+ * Path helpers for the KakaoTalk (`lazykatok`) datasource skill.
+ *
+ * All paths are workspace-relative and live under
+ * `<workspaceRoot>/.autorag/datasources/lazykatok`. The client never exposes raw
+ * filesystem paths to callers; chunk identifiers are surfaced as opaque
+ * slash-hierarchical sources of the form
+ * `/kakao/<instance-id>/chunks/<chunk-id>`.
+ */
+export declare const AUTORAG_DIRNAME = ".autorag";
+export declare const DATASOURCES_DIRNAME = "datasources";
+export declare const LAZYKATOK_DATASOURCE_DIRNAME = "lazykatok";
+/** Logical datasource kind for source identifiers. */
+export declare const LAZYKATOK_SOURCE_KIND: "kakao";
+/**
+ * Root directory for lazykatok-managed state under a workspace. This is where the
+ * external `lazykatok` CLI stores its index, chunks, and sync state.
+ */
+export declare function lazykatokDatasourceRoot(workspaceRoot: string): string;
+/** Directory holding the lazykatok chunk index. */
+export declare function lazykatokIndexPath(workspaceRoot: string): string;
+/** Directory holding materialized lazykatok chunks. */
+export declare function lazykatokChunksPath(workspaceRoot: string): string;
+/** Directory holding lazykatok sync state. */
+export declare function lazykatokSyncPath(workspaceRoot: string): string;
+/**
+ * Builds the path-opaque, slash-hierarchical source identifier for a single
+ * lazykatok chunk. Callers (the LazykatokSkill methods) use this to populate
+ * `RetrievalResult.source` so no real filesystem path ever leaks.
+ */
+export declare function lazykatokSourcePath(instanceId: string, chunkId: string): string;
+/**
+ * Parses a lazykatok source identifier back into its `{ instanceId, chunkId }`
+ * components. Returns `undefined` for malformed or non-kakao sources so that
+ * deny decisions remain explicit rather than undefined-as-deny.
+ */
+export declare function parseLazykatokSourcePath(source: string): {
+    readonly instanceId: string;
+    readonly chunkId: string;
+} | undefined;

package/dist/datasource/skills/{katok → lazykatok}/skill.d.ts

@@ -1,28 +1,28 @@
 import type { RetrievalMethod } from "../../../retrieval/types.js";
 import type { DatasourceIndexResult, DatasourceSkill, DatasourceSkillDescriptor, DatasourceSkillManifest, PollingMetadata, SourceDescription } from "../../types.js";
-import { type KatokSearchClient } from "./methods.js";
-import type { KatokDoctorResult, KatokIndexResult, KatokSyncResult } from "./types.js";
-export interface KatokSkillClient extends KatokSearchClient {
-    doctor(): Promise<KatokDoctorResult>;
-    sync(): Promise<KatokSyncResult>;
-    index(): Promise<KatokIndexResult>;
+import { type LazykatokSearchClient } from "./methods.js";
+import type { LazykatokDoctorResult, LazykatokIndexResult, LazykatokSyncResult } from "./types.js";
+export interface LazykatokSkillClient extends LazykatokSearchClient {
+    doctor(): Promise<LazykatokDoctorResult>;
+    sync(): Promise<LazykatokSyncResult>;
+    index(): Promise<LazykatokIndexResult>;
 }
-export interface KatokSkillOptions {
-    readonly client: KatokSkillClient;
+export interface LazykatokSkillOptions {
+    readonly client: LazykatokSkillClient;
     readonly instanceId?: string;
     readonly instances?: readonly string[];
     readonly pollingIntervalMs?: number;
     readonly tags?: readonly string[];
     readonly lastIndexedAt?: number;
 }
-export declare class KatokSkill implements DatasourceSkill {
+export declare class LazykatokSkill implements DatasourceSkill {
     private readonly client;
     private readonly instanceId;
     private readonly instances;
     private readonly pollingIntervalMs;
     private readonly tags;
     private lastIndexedAt;
-    constructor(options: KatokSkillOptions);
+    constructor(options: LazykatokSkillOptions);
     describe(): DatasourceSkillDescriptor;
     polling(): PollingMetadata;
     index(): Promise<DatasourceIndexResult>;