@autorag/librarian 2.0.0

package/dist/subagents/dispatch-validation.d.ts

@@ -0,0 +1,169 @@
+export type DispatchRejectionCode = "DISPATCH_MALFORMED" | "DISPATCH_ACTION_UNKNOWN" | "DISPATCH_ADMIN_MUTATION_FORBIDDEN" | "DISPATCH_CONTROL_FORBIDDEN" | "DISPATCH_SCHEDULE_FORBIDDEN" | "DISPATCH_ARTIFACTS_INVALID" | "DISPATCH_AGENT_SCOPE_INVALID" | "DISPATCH_AGENT_IDENTITY" | "DISPATCH_MODEL_MISMATCH" | "DISPATCH_ASSIGNMENT_INVALID" | "DISPATCH_QUERY_MISMATCH" | "DISPATCH_CWD_MISSING" | "DISPATCH_CWD_OUTSIDE_ROOTS" | "DISPATCH_NO_ACTIVE_QUERY";
+export type DispatchKind = "launch" | "admin" | "control" | "mutation" | "schedule" | "hybrid" | "unknown";
+export interface DispatchRejection {
+    readonly code: DispatchRejectionCode;
+    readonly field: string;
+    readonly dispatchKind: DispatchKind;
+}
+export declare class DispatchRejectionError extends Error {
+    readonly code: DispatchRejectionCode;
+    readonly field: string;
+    readonly exactFix: string;
+    readonly forceCorrectable: boolean;
+    readonly skeleton: string;
+    readonly dispatchKind: DispatchKind;
+    constructor(rejection: DispatchRejection, exactFix: string, forceCorrectable: boolean, skeleton: string);
+}
+export declare const EXACT_FIX_MAP: Readonly<Record<DispatchRejectionCode, string>>;
+export declare const FORCE_CORRECTABLE_MAP: Readonly<Record<DispatchRejectionCode, boolean>>;
+/** Backward-compatible aliases for the shared skeleton literals from dispatch-templates.ts. */
+export declare const SKELETON_ADMIN = "{\"action\":\"list\"}";
+export declare const SKELETON_SINGLE = "{\"agentScope\":\"user\",\"artifacts\":false,\"agent\":\"autorag-explorer\",\"model\":\"<configured-model>\",\"cwd\":\"<allowed-root>\",\"task\":\"<Assignment V1 block>\"}";
+export declare const SKELETON_FANOUT = "{\"agentScope\":\"user\",\"artifacts\":false,\"tasks\":[{\"agent\":\"autorag-explorer\",\"model\":\"<configured-model>\",\"cwd\":\"<allowed-root>\",\"task\":\"<Assignment V1 block>\"}]}";
+export declare function formatBlockReason(code: DispatchRejectionCode, field: string, exactFix: string, skeleton: string): string;
+export declare function classifyAction(action: unknown): DispatchKind;
+/**
+ * Classify a full dispatch invocation into a dispatch kind.
+ *
+ * Classification happens BEFORE any defaults or autofill.
+ * - If `action` is present and is a mutation/control/schedule → that kind (forbidden-action precedence).
+ * - If `action` is present and is a diagnostic (exact lowercase) → admin.
+ * - If `action` is present and is an explicit execution alias (exact lowercase: single/parallel/tasks) with launch shape → launch.
+ * - If `action` is present but is non-string, unknown, or a non-exact-lowercase value
+ *   (e.g. "Create", "LIST", "Interrupt", 42) → unknown, regardless of launch fields.
+ * - If no `action` property but launch shape fields present (agent/task/tasks/chain/parallel) → launch.
+ * - Otherwise → unknown.
+ */
+export declare function classifyDispatch(args: unknown): DispatchKind;
+/**
+ * Validate a diagnostic invocation against its exact allowed field set.
+ * Returns a DispatchRejection if invalid, undefined if valid.
+ * Diagnostics bypass explorer assignment/root/model launch gates.
+ */
+export declare function validateDiagnostic(args: Record<string, unknown>, action: string): DispatchRejection | undefined;
+export declare function rejectForbiddenAction(action: string): DispatchRejection;
+export interface PrepareContext {
+    /** Configured explorer model wire id (e.g. "provider/model-id"). */
+    readonly configuredModel: string | undefined;
+}
+export interface PrepareResult {
+    /** Normalized args (defaults filled for launch, null-deleted). */
+    readonly args: Record<string, unknown>;
+    /** Whether any field was autofilled. */
+    readonly autofilled: {
+        readonly artifacts: boolean;
+        readonly agentScope: boolean;
+        readonly leafModelFillCount: number;
+    };
+}
+/**
+ * Composed prepareArguments for the subagent tool.
+ *
+ * Classifies first, then applies launch-only normalization (null-delete + missing defaults).
+ * Diagnostics never receive artifacts/agentScope/model defaults.
+ * Throws DispatchRejectionError on any validation failure.
+ */
+export declare function autoragPrepare(rawArgs: unknown, ctx: PrepareContext): Record<string, unknown>;
+export declare function readAutofilled(args: Record<string, unknown>): {
+    readonly artifacts: boolean;
+    readonly agentScope: boolean;
+    readonly leafModelFillCount: number;
+} | undefined;
+interface LaunchLeaf {
+    readonly record: Record<string, unknown>;
+    readonly path: string;
+}
+export declare function getLaunchLeaves(args: Record<string, unknown>): readonly LaunchLeaf[];
+/**
+ * Create a DispatchRejectionError from a DispatchRejection with proper
+ * exactFix, forceCorrectable, and skeleton selection.
+ * Used by beforeToolCall for post-schema rejections.
+ *
+ * When `args` is provided and the rejection is a launch kind, the skeleton is
+ * selected from the args shape: fanout if `tasks`/`chain`/`parallel` are
+ * present, single otherwise. When `args` is omitted, launch rejections default
+ * to the single skeleton. Non-launch kinds always use the admin skeleton.
+ */
+export declare function createDispatchRejectionError(rejection: DispatchRejection, args?: Record<string, unknown>): DispatchRejectionError;
+/** Backward-compatible aliases for shared V1 sentinel constants. */
+export declare const AUTORAG_ASSIGNMENT_V1_START = "<<<AUTORAG_ASSIGNMENT_V1>>>";
+export declare const AUTORAG_ASSIGNMENT_V1_END = "<<<END_AUTORAG_ASSIGNMENT_V1>>>";
+export interface ParsedAssignment {
+    readonly originalQuery: string;
+    readonly method: string;
+    readonly queryVariants: readonly string[];
+    /** Whether V1 (true) or legacy (false) format was used. */
+    readonly isV1: boolean;
+}
+/** Backward-compatible aliases for shared role line constants. */
+export declare const ROLE_LINE_RETRIEVED_AT = "Required handoff: include retrievedAt.";
+export declare const ROLE_LINE_TEMPORAL_METADATA = "Required handoff: include temporal metadata.";
+export declare function canonicalRoleLines(): string;
+/**
+ * Parse a task string as an Assignment V1 block.
+ *
+ * V1 sentinels:
+ * - Start line (after stripping single trailing CR) must equal <<<AUTORAG_ASSIGNMENT_V1>>>
+ * - End line (after stripping single trailing CR) must equal <<<END_AUTORAG_ASSIGNMENT_V1>>>
+ * - End sentinel at EOF valid
+ * - Exactly one V1 block; duplicate/malformed/unterminated → reject
+ * - Body: one JSON object with exactly keys originalQuery, method, queryVariants
+ * - originalQuery: string, trimmed nonempty
+ * - method: string, trimmed nonempty
+ * - queryVariants: nonempty array of nonempty strings
+ * - Extra/missing keys/wrong types → reject
+ *
+ * Returns undefined if no V1 sentinel found (caller should try legacy).
+ * Returns ParsedAssignment on success.
+ * Throws DispatchRejectionError on malformed V1.
+ */
+export declare function parseAssignmentV1(task: string): ParsedAssignment | undefined;
+/**
+ * Parse a task string as a legacy prose assignment.
+ *
+ * Legacy (n4 retained):
+ * - Full logical lines; optional leading whitespace; optional `- ` bullet; optional matching `**` around label.
+ * - Case/space normalize labels; value = remainder of same line only.
+ * - Labels: Original query; Selected retrieval method | Retrieval method; Query variants | Query variant.
+ * - Reorder OK; exactly once each; Query variants split on `;`, trim, reject empty segments.
+ * - Later label-looking line → reject.
+ * - Prefix/suffix outside three lines preserved.
+ * - Multiline / special / label-looking content inside values → V1 required, not legacy.
+ *
+ * Returns undefined if no legacy labels found.
+ * Throws DispatchRejectionError on malformed legacy.
+ */
+export declare function parseLegacyAssignment(task: string): ParsedAssignment | undefined;
+/**
+ * Parse a task string as either V1 or legacy assignment.
+ * Tries V1 first; if no V1 sentinels, tries legacy.
+ * Returns undefined if neither format is found.
+ * Throws DispatchRejectionError on malformed input.
+ */
+export declare function parseAssignment(task: string): ParsedAssignment | undefined;
+/**
+ * Insert canonical role lines into a task string, byte-idempotent.
+ *
+ * 1. Remove all existing exact canonical role lines (the two literals after CR-strip).
+ * 2. Insert exactly one of each immediately after end sentinel (V1) or
+ *    immediately after the last of the three recognized legacy label lines.
+ * 3. Preserve all other suffix bytes and original newline style.
+ * 4. Repeat rendering is byte-idempotent.
+ */
+export declare function ensureRoleLines(task: string): string;
+export interface PostSchemaContext {
+    readonly configuredModel: string | undefined;
+    readonly currentQuery: string | undefined;
+    readonly allowedRoots: readonly string[];
+    readonly workspaceRoot: string;
+}
+/**
+ * Post-schema validation for launch invocations.
+ * Checks: assignment parse, structural query equality, role lines,
+ * cwd realpath/allowed roots, model match.
+ *
+ * Returns a DispatchRejection if invalid, undefined if valid.
+ * Also normalizes cwd to canonical realpath on success.
+ */
+export declare function validateLaunchPostSchema(args: Record<string, unknown>, ctx: PostSchemaContext): DispatchRejection | undefined;
+export {};

package/dist/subagents/explorer-tools-extension.d.ts

@@ -0,0 +1,4 @@
+import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+type ExplorerToolRegistrar = Pick<ExtensionAPI, "registerTool">;
+export default function registerExplorerTools(pi: ExplorerToolRegistrar): void;
+export {};

package/dist/subagents/explorer-tools-extension.js

@@ -0,0 +1,130 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// src/subagents/explorer-tools-extension.ts
+import { realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createReadToolDefinition
+} from "@earendil-works/pi-coding-agent";
+var PARENT_TRAVERSAL_SEGMENT = /(^|[/\\])\.\.($|[/\\])/;
+var TOOL_METADATA_CWD = "/";
+
+class ExplorerPathContainmentError extends Error {
+  code;
+  requestedPath;
+  root;
+  constructor(message, requestedPath, root) {
+    super(message);
+    this.name = "ExplorerPathContainmentError";
+    this.code = "EXPLORER_PATH_CONTAINMENT";
+    this.requestedPath = requestedPath;
+    this.root = root;
+  }
+}
+function isMissingPathError(error) {
+  return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
+}
+function isEqualOrDescendant(root, target) {
+  const pathFromRoot = relative(root, target);
+  return pathFromRoot === "" || pathFromRoot !== ".." && !pathFromRoot.startsWith(`..${sep}`) && !isAbsolute(pathFromRoot);
+}
+async function resolveExistingTargetOrNearestParent(target) {
+  try {
+    return await realpath(target);
+  } catch (error) {
+    if (!isMissingPathError(error))
+      throw error;
+  }
+  let candidateParent = dirname(target);
+  while (true) {
+    try {
+      const realParent = await realpath(candidateParent);
+      return resolve(realParent, relative(candidateParent, target));
+    } catch (error) {
+      if (!isMissingPathError(error))
+        throw error;
+      const nextParent = dirname(candidateParent);
+      if (nextParent === candidateParent)
+        throw error;
+      candidateParent = nextParent;
+    }
+  }
+}
+async function resolveExplorerRoot(cwd) {
+  const root = await realpath(cwd);
+  if (!(await stat(root)).isDirectory()) {
+    throw new Error(`Explorer assigned cwd is not a directory: ${cwd}`);
+  }
+  return root;
+}
+async function resolveContainedPath(root, requestedPath) {
+  if (PARENT_TRAVERSAL_SEGMENT.test(requestedPath)) {
+    throw new ExplorerPathContainmentError(`Explorer filesystem containment rejected parent traversal path: ${requestedPath}`, requestedPath, root);
+  }
+  const target = await resolveExistingTargetOrNearestParent(resolve(root, requestedPath));
+  if (!isEqualOrDescendant(root, target)) {
+    throw new ExplorerPathContainmentError(`Explorer filesystem containment rejected path outside assigned cwd: ${requestedPath}`, requestedPath, root);
+  }
+  return { root, target };
+}
+function registerExplorerTools(pi) {
+  let pinnedRoot;
+  const getPinnedRoot = (cwd) => {
+    pinnedRoot ??= resolveExplorerRoot(cwd);
+    return pinnedRoot;
+  };
+  const readTool = createReadToolDefinition(TOOL_METADATA_CWD);
+  pi.registerTool({
+    ...readTool,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { root, target } = await resolveContainedPath(await getPinnedRoot(ctx.cwd), params.path);
+      return createReadToolDefinition(root).execute(toolCallId, { ...params, path: target }, signal, onUpdate, ctx);
+    }
+  });
+  const grepTool = createGrepToolDefinition(TOOL_METADATA_CWD);
+  pi.registerTool({
+    ...grepTool,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { root, target } = await resolveContainedPath(await getPinnedRoot(ctx.cwd), params.path ?? ".");
+      return createGrepToolDefinition(root).execute(toolCallId, { ...params, path: target }, signal, onUpdate, ctx);
+    }
+  });
+  const findTool = createFindToolDefinition(TOOL_METADATA_CWD);
+  pi.registerTool({
+    ...findTool,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { root, target } = await resolveContainedPath(await getPinnedRoot(ctx.cwd), params.path ?? ".");
+      return createFindToolDefinition(root).execute(toolCallId, { ...params, path: target }, signal, onUpdate, ctx);
+    }
+  });
+  const lsTool = createLsToolDefinition(TOOL_METADATA_CWD);
+  pi.registerTool({
+    ...lsTool,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const { root, target } = await resolveContainedPath(await getPinnedRoot(ctx.cwd), params.path ?? ".");
+      return createLsToolDefinition(root).execute(toolCallId, { ...params, path: target }, signal, onUpdate, ctx);
+    }
+  });
+}
+export {
+  registerExplorerTools as default
+};

package/dist/subagents/local-models.d.ts

@@ -0,0 +1,14 @@
+import type { Model } from "@earendil-works/pi-ai";
+export interface LocalAutoRAGModels {
+    readonly provider: string;
+    readonly apiKey: string;
+    readonly orchestrator: Model<"openai-responses">;
+    readonly explorer: Model<"openai-responses">;
+}
+export interface LoadLocalAutoRAGModelsOptions {
+    readonly configPath?: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
+    readonly orchestratorModelId?: string;
+    readonly explorerModelId?: string;
+}
+export declare function loadLocalAutoRAGModels(options?: LoadLocalAutoRAGModelsOptions): LocalAutoRAGModels;

package/dist/subagents/model-policy.d.ts

@@ -0,0 +1,31 @@
+export declare const ORCHESTRATOR_MODEL_ID: "gpt-5.6-sol";
+export declare const EXPLORER_MODEL_ID: "gpt-5.6-luna";
+export declare const REQUIRED_MODEL_IDS: Readonly<{
+    orchestrator: "gpt-5.6-sol";
+    explorer: "gpt-5.6-luna";
+}>;
+export type ModelRole = keyof typeof REQUIRED_MODEL_IDS;
+export interface ModelReference {
+    readonly id: string;
+    readonly provider?: string;
+}
+export interface ValidatedModelPolicy {
+    readonly orchestrator: ModelReference;
+    readonly explorer: ModelReference;
+}
+export type ModelPolicyErrorCode = "INVALID_POLICY_OBJECT" | "MISSING_REQUIRED_MODEL" | "INVALID_MODEL_REFERENCE";
+export declare class ModelPolicyError extends Error {
+    readonly code: ModelPolicyErrorCode;
+    readonly role?: ModelRole;
+    readonly expected?: string;
+    readonly actual?: string;
+    constructor(code: ModelPolicyErrorCode, message: string, options?: {
+        readonly role?: ModelRole;
+        readonly expected?: string;
+        readonly actual?: string;
+    });
+}
+export declare function validateModelPolicy(value: unknown): ValidatedModelPolicy;
+export declare function assertModelPolicy(value: unknown): asserts value is ValidatedModelPolicy;
+export declare function isModelPolicy(value: unknown): value is ValidatedModelPolicy;
+export declare function requiredModelId(role: ModelRole): string;

package/dist/subagents/runtime.d.ts

@@ -0,0 +1,52 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { type Api, type Model } from "@earendil-works/pi-ai";
+import { type AgentSession } from "@earendil-works/pi-coding-agent";
+export declare const EXPLORER_TOOLS_EXTENSION_PATH: string;
+export declare const AUTORAG_EXPLORER_AGENT_MANAGED_VERSION = 2;
+export declare const AUTORAG_EXPLORER_AGENT_DEFINITION: string;
+export interface MandatorySubagentSessionOptions {
+    readonly cwd: string;
+    readonly model: Model<Api>;
+    readonly explorerModel?: Model<Api>;
+    readonly systemPrompt: string;
+    readonly tools: readonly AgentTool[];
+    readonly extensionPath?: string;
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+    readonly agentDir?: string;
+    readonly sessionDir?: string;
+}
+export interface MandatorySubagentSession {
+    readonly session: AgentSession;
+    readonly extensionPath: string;
+}
+export interface HealthSubagentProbeSessionOptions {
+    readonly cwd: string;
+    readonly model: Model<Api>;
+    readonly explorerModel?: Model<Api>;
+    readonly systemPrompt: string;
+    readonly tools: readonly AgentTool[];
+    readonly extensionPath?: string;
+    readonly apiKey?: string;
+    readonly providerApiKeys?: Readonly<Record<string, string>>;
+    readonly agentDir: string;
+    readonly sessionDir: string;
+}
+export interface HealthSubagentProbeSession {
+    readonly session: AgentSession;
+    readonly extensionPath: string;
+    readonly dispose: () => void;
+}
+export declare function createMandatorySubagentSession(options: MandatorySubagentSessionOptions): Promise<MandatorySubagentSession>;
+/**
+ * Create a short-lived subagent session for the `autorag health` explorer probe.
+ *
+ * Unlike {@link createMandatorySubagentSession}, this requires absolute
+ * `agentDir` and `sessionDir` (typically under a caller-created temp
+ * directory) so the probe never touches durable home state. On a lease
+ * conflict — i.e. when another live session holds a different child
+ * environment/registry routing — the error is rethrown with a stable
+ * "concurrent AutoRAG session busy" message so the health command can map
+ * it to `subagent_failed`.
+ */
+export declare function createHealthSubagentProbeSession(options: HealthSubagentProbeSessionOptions): Promise<HealthSubagentProbeSession>;

package/dist/tool/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class NotImplementedError extends Error {
+    readonly methodName: string;
+    constructor(methodName: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1 @@
+export { NotImplementedError } from "./errors.js";

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@autorag/librarian",
+  "version": "2.0.0",
+  "description": "Self-evolving librarian agent on Pi framework with pluggable retrieval methods",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Marker-Inc-Korea/AutoRAG.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "autorag": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build src/index.ts src/cli/index.ts src/subagents/explorer-tools-extension.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": "vitest run",
+    "check": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.10",
+    "@earendil-works/pi-ai": "^0.80.10",
+    "@earendil-works/pi-coding-agent": "0.80.10",
+    "@opendataloader/pdf": "^2.4.7",
+    "@pngwasi/node-tantivy-binding": "^0.3.4",
+    "chardet": "^2.2.0",
+    "fast-xml-parser": "^5.9.3",
+    "iconv-lite": "^0.7.2",
+    "jszip": "^3.10.1",
+    "mailparser": "^3.9.12",
+    "pi-subagents": "0.35.1",
+    "slides-grab": "^1.3.1",
+    "smol-toml": "1.7.0",
+    "tesseract.js": "^7.0.0",
+    "typebox": "^1.1.24",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.5",
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.7.3",
+    "vitest": "^4.1.10"
+  }
+}

package/skills/autorag/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: autorag
+description: Use an already configured AutoRAG librarian agent to search, summarize, compare, and answer questions from local document collections. Use autorag-setup instead for provider/model discovery, first-time configuration, or selecting folders to index.
+---
+
+# AutoRAG Librarian Skill
+
+Use this skill when AutoRAG is already configured and the user asks to search,
+summarize, compare, or answer questions from local PDFs, wikis, notes, research
+papers, or knowledge bases. For first-time configuration, missing model/provider
+settings, subscription or API-provider detection, or changing indexed folders,
+use the `autorag-setup` skill instead.
+
+AutoRAG is invoked through the `autorag` CLI. It is non-destructive: it reads
+source files and writes indexes under the configured workspace's `.autorag/`
+directory and, when enabled, Jikji's per-source `.jikji/` caches. Never move,
+rename, or delete source files.
+
+## Preflight
+
+Confirm that `~/.autorag/config.json` exists (or an explicit `--config` /
+`AUTORAG_CONFIG` path). Inspect that non-secret config for usable
+`searchPaths`/`agents` without printing credentials. Then run:
+
+```bash
+autorag status
+autorag health
+```
+
+`status` is model-free and path-opaque: it reports corpus freshness and index
+health, not absolute filesystem paths or role-model auth. `health` checks
+model/provider auth and explorer subagent setup: it resolves both role models,
+verifies credential presence, and (unless `--skip-probes`) probes a completion
+call per role. Use `health` to diagnose model, provider, auth, timeout, or
+subagent dispatch failures before searching. If configuration, authentication,
+role models, or indexes are missing or unhealthy, stop this workflow and use
+`autorag-setup`; do not guess private providers or model IDs.
+
+## Searching
+
+```bash
+autorag search "what were the key findings in the Q3 report" --top-k 5
+```
+
+AutoRAG returns curated, numbered knowledge units grounded in sources plus a
+`sessionId` needed for feedback. Use:
+
+- `--scope` to narrow to a configured virtual sub-path
+- `--tags tag1,tag2` only when trusted datasource access is already configured
+  server-side; tags narrow already-allowed results and never grant new access
+- `--json` for structured output (`sessionId`, numbered `results`, `answer`)
+- `--debug` only when diagnostics are needed
+
+Do not bypass AutoRAG with ad hoc raw search when the user explicitly requested
+the librarian agent. Search requires a resolvable orchestrator/explorer model
+pair from config, flags, env, or the authenticated local runtime. When `autorag
+search` fails for a model, provider, auth, timeout, or subagent reason, the
+error output includes a hint pointing to `autorag health` for diagnosis.
+
+Record feedback so retrieval memory learns which results were useful:
+
+```bash
+autorag feedback <sessionId> --useful 1,3 --not-useful 2
+```
+
+Supply at least one of `--useful` or `--not-useful`. Numbers refer to the
+numbered knowledge units from that session's search output.
+
+## Maintenance
+
+```bash
+autorag status
+autorag health
+autorag refresh
+autorag refresh --method bm25,minsync
+autorag watch --once
+autorag watch
+autorag refresh --force
+autorag index rebuild --yes
+autorag index reset --method bm25 --yes
+autorag memory inspect
+```
+
+Use `refresh` after source documents change (parses sources and resyncs BM25 /
+MinSync / datasources / optional Jikji prepare). Prefer bounded refresh over
+reset. `watch --once` is the preferred single tick for scheduled jobs; long-running
+`watch` keeps an fs event loop open for interactive sessions.
+`--method <csv>` (e.g. `--method bm25,minsync,parsed`) restricts which methods
+refresh/index run; when omitted all methods run. BM25 and MinSync are enabled
+by default — no explicit configuration is needed for standard lexical + semantic
+retrieval. MinSync uses a pre-installed binary (`autoInstall: false`); configure
+`minSync.embedder` via `autorag init --embedder-*` flags for remote embedding.
+
+### Keep indexes fresh on a schedule (agent responsibility)
+
+There is **no always-on network service** in the CLI. Agents and operators must
+install an OS-appropriate periodic job that runs a model-free index tick:
+
+```bash
+# Preferred scheduled command (single non-daemon refresh)
+NODE_OPTIONS=--max-old-space-size=16384 autorag watch --once
+# Equivalent one-shot refresh
+NODE_OPTIONS=--max-old-space-size=16384 autorag refresh
+```
+
+Schedule guidance by OS (typical interval: every 15–30 minutes; never more often
+than the corpus can finish refreshing):
+
+| OS | Preferred scheduler | Pattern |
+|---|---|---|
+| macOS | `cron` or `launchd` (`~/Library/LaunchAgents`) | `*/30 * * * * ... autorag watch --once` or a KeepAlive=false StartInterval plist |
+| Linux | `cron` / `systemd --user` timer | crontab `*/30 * * * *` or a oneshot service + timer |
+| Windows | Task Scheduler | repeating task every 30 minutes running `autorag watch --once` under the user profile |
+
+Rules for scheduled watch:
+
+1. Prefer `autorag watch --once` (or `autorag refresh`) over a permanent
+   long-running `autorag watch` daemon in user agents — daemons die on reboot
+   and are harder to supervise from skill workflows.
+2. Use the same config the search path uses (`~/.autorag/config.json` or an
+   explicit `--config` / `AUTORAG_CONFIG`).
+3. Raise Node heap for large home trees: `NODE_OPTIONS=--max-old-space-size=16384`.
+4. Redirect logs somewhere under the home/user temp tree, never into source
+   document folders.
+5. After install/setup, **create or verify** the scheduled job before claiming
+   ongoing indexing is covered. Re-check with `crontab -l`, `systemctl --user list-timers`,
+   or Task Scheduler inspection when the user asks about freshness.
+6. Do not schedule concurrent overlapping ticks; if a prior refresh is still
+   running, skip or wait (lock/log rather than stampeding MiniSync/BM25 writers).
+
+Destructive index commands:
+
+- `autorag index reset --yes` removes parsed, BM25, and MinSync directories under
+  workspace `.autorag` only. Add `--method bm25|minsync|parsed` to scope which
+  indexes are removed (e.g. `--method bm25` removes only the BM25 index).
+- `autorag index rebuild --yes` resets those indexes then forced-refreshes.
+  `--method` scopes both the reset and the rebuild refresh.
+
+Never run reset/rebuild against source documents. `memory inspect` is
+read-only and path-opaque.
+
+## Rules
+
+- Use only configured and approved search paths.
+- Never expose provider credentials or authentication payloads.
+- Never invent or reveal private provider names or model IDs.
+- Never treat a consumer subscription as API access without runtime evidence.
+- Preserve real source mapping and numbered feedback identifiers.
+- Prefer `--json` when another agent must consume the result programmatically.