@autorag/librarian 2.6.3 → 2.8.0

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

@@ -1,245 +0,0 @@
----
-name: autorag-lite-search
-description: Retrieve documents from an indexed AutoRAG Lite corpus without a model, then persist externally curated reports, inspect evidence, and record numbered feedback. Use when the user wants model-free search, scoped or tag-narrowed retrieval, or the report/evidence/feedback workflow over local documents and authorized datasources.
-license: MIT
----
-
-# AutoRAG Lite search
-
-Use this skill when AutoRAG Lite is already configured and indexed, and the
-user wants model-free retrieval, or wants to persist an externally curated
-report, inspect its evidence, or record feedback. Use `autorag-lite-setup`
-when config, indexing, or refresh is missing or broken. Use the `autorag`
-skill when a model-backed curated answer is requested.
-
-AutoRAG Lite never mutates sources. Retrieval reads local source documents and
-authorized datasource content; writes go only to workspace `.autorag/` indexes,
-the memory file, and Jikji `.jikji/` caches.
-
-## Preflight
-
-Retrieval needs a completed refresh. If `autorag lite retrieve` returns exit
-code 2 with an `index-not-ready` diagnostic, no refresh has completed yet —
-run `autorag lite refresh` (or `autorag refresh`) first, then retry. Confirm
-freshness with:
-
-```bash
-autorag lite status --json
-```
-
-`status` is model-free and path-opaque, and its `stale` field is read from disk,
-so it answers "is indexing complete?" even from a fresh process.
-
-A stale corpus is not a failure: `retrieve` answers from the index it has and
-reports the staleness it is answering past (`"stale": true` plus `stale-index`
-diagnostics). Pass `--refresh` to rebuild incrementally before answering, or
-`--strict` to keep the old fail-closed behavior and exit 2 instead of answering.
-
-## Retrieve
-
-```bash
-autorag lite retrieve "key findings in the Q3 report" --top-k 5 --json
-```
-
-The JSON envelope is:
-
-```json
-{
-  "ok": true,
-  "query": "key findings in the Q3 report",
-  "stale": false,
-  "results": [
-    {
-      "number": 1,
-      "source": "<opaque source identifier>",
-      "method": "minsync",
-      "score": 0.83,
-      "metadata": {},
-      "content": "..."
-    }
-  ],
-  "unsearched": [],
-  "diagnostics": []
-}
-```
-
-- `--top-k N` must be a positive integer. Invalid values exit with code 2 and
-  an `{"ok": false, "error": "..."}` rejection envelope.
-- Before any refresh, the envelope is `{"ok": false, "query": ..., "diagnostics":
-  [{"code": "index-not-ready", "severity": "error", ...}]}` with exit code 2.
-- `stale: true` means the last refresh does not cover the current sources; the
-  results are still returned. Each entry in `diagnostics` with code
-  `stale-index` names the opaque source and a `reason` (for example
-  `mtime-and-size-changed`) plus `action: "refresh"`. Sources the refresh
-  deliberately skipped (exact duplicates, oversized or unparseable files, and
-  AutoRAG/Jikji product artifacts) are not stale.
-- `--refresh` runs an incremental refresh before answering and reports the
-  corpus current; `--strict` exits 2 with the `index-not-ready` envelope when the
-  index is stale, for callers that must not answer from a stale index.
-- Each result carries a provenance pair: the `source` identity and the
-  `method` that produced it. Source identities are source-native: real file
-  paths for local files, datasource identities for datasource results. Never
-  rewrite, guess, or flatten them.
-- `unsearched` lists the retrieval surfaces that did not run for this query.
-  `ok: true` with a non-empty `unsearched` means the answer is partial: for
-  example local MinSync files are skipped while an index sync holds the
-  workspace lock, leaving only datasource hits. Check `unsearched.length > 0`
-  before concluding that the returned sources are the whole corpus. Each entry
-  is:
-
-  ```json
-  {
-    "surface": "minsync",
-    "methods": ["hybrid", "minsync"],
-    "reason": "MinSyncQueryError: another sync is in progress (/Users/me/corpus/.autorag/minsync)"
-  }
-  ```
-
-  `surface` is `minsync` for local files or the datasource id. `reason` is the
-  underlying failure verbatim — the CLI's failure kind, exit status, stderr and
-  real paths — so the operator can act on it directly. Report it to the user as
-  given; do not summarize it away.
-- `diagnostics` carry the same transparency: `source` is the component or
-  method label, `reason` repeats the underlying error, and codes include
-  `retrieval-method-failed` and `minsync-unavailable`. A degraded component
-  produces a diagnostic, not a failed run; check `diagnostics` before trusting
-  an empty result set.
-- `--debug` adds per-result metadata and the diagnostics list to human output.
-  Skipped-surface warnings print without it, and their reasons carry real
-  filesystem paths.
-- Exit codes: 0 on success (results may be empty, and a stale index is a
-  warning rather than a failure), 2 for usage, config, not-ready, or
-  `--strict` staleness errors, 1 for runtime errors.
-
-Retrieval methods run in parallel and merge: parsed mirrors and MinSync
-lexical/vector/hybrid methods, plus configured datasource methods. Jikji is a
-local discovery/indexing preparer, not a retrieval method in the lite registry.
-`--method` selection applies to refresh, not retrieve; retrieval always queries
-every active retrieval method.
-
-## Scope and tag narrowing (default-deny)
-
-Datasource access is default-deny from trusted config
-(`datasourceAccess.allowedTags`, `allowedScopes`). Retrieval flags can only
-narrow that access, never widen it:
-
-- `--scope SCOPE` narrows datasource retrieval to a requested sub-path; it
-  cannot grant access to anything the config does not already allow.
-- `--tags tag1,tag2` further narrows already-authorized datasource results by
-  intersecting with configured allowed tags; it never grants new access.
-
-## Persisting a curated report
-
-An external agent curates the raw retrieval results, then persists the
-structured report so evidence and feedback commands work against it:
-
-```bash
-autorag lite report "key findings in the Q3 report" --input report.json --json
-cat report.json | autorag lite report "key findings in the Q3 report" --json
-```
-
-The input is the `emit_autorag_results` JSON schema. Every field below that is
-not marked optional is required — `results[].evidence` and `mapping[].content`
-are the two that are easiest to forget:
-
-- `answer` (string) — the curated answer, citing results as `[1]`, `[2]`.
-- `results` (array) — one entry per numbered knowledge unit, each with
-  `number` (1-based integer), `title` (string), `summary` (string),
-  `evidence` (array of `{"excerpt": "..."}` objects, each with an optional
-  `lineNumber`), and `confidence` (number in `[0, 1]`). A result carries no
-  `source`; source identity lives in `mapping`.
-- `mapping` (array) — exactly one entry per result `number`, each with
-  `number`, `source` (the opaque identity carried from retrieve), `method`,
-  and `content` (the raw snippet kept for feedback tracking). `evidenceRefs`
-  is optional; each ref needs `method` and `source` and may add `excerpt`,
-  `content`, `chunkIndex`, `lineNumber`, `retrievalResultId`, and
-  `confidence` in `[0, 1]`.
-- `warnings` (optional array of strings).
-
-Result and mapping numbers must be one-to-one positive integers, and every
-`confidence` must be in `[0, 1]`. A complete minimal input:
-
-```json
-{
-  "answer": "[1] Refund exceptions need director approval before payout.",
-  "results": [
-    {
-      "number": 1,
-      "title": "Refund exception approval",
-      "summary": "Refund exceptions require director approval before payout.",
-      "evidence": [
-        {
-          "excerpt": "Refund exceptions require director approval.",
-          "lineNumber": 12
-        }
-      ],
-      "confidence": 0.9
-    }
-  ],
-  "mapping": [
-    {
-      "number": 1,
-      "source": "/Users/me/corpus/refund-policy.txt",
-      "method": "minsync",
-      "content": "Refund exceptions require director approval before payout."
-    }
-  ],
-  "warnings": []
-}
-```
-
-Invalid input exits with code 2 and `{"ok": false, "error": "..."}`. The
-rejection names every field that failed, by JSON path, so fix exactly what it
-points at instead of guessing:
-
-```text
-{"ok": false, "error": "Invalid report: expected the emit_autorag_results JSON schema (/results/0: must have required properties evidence; /mapping/0: must have required properties content)"}
-```
-
-`source` values in a report are opaque identifiers carried from retrieval
-output. Report persistence performs no filesystem reads against them; it
-stores the identifiers as given. Preserve the exact source-native identities
-from the retrieve envelope.
-
-On success the JSON envelope is:
-
-```json
-{
-  "ok": true,
-  "sessionId": "<uuid>",
-  "query": "key findings in the Q3 report",
-  "answer": "...",
-  "resultCount": 3
-}
-```
-
-Use the returned `sessionId` for evidence inspection and feedback.
-
-## Evidence and feedback
-
-```bash
-autorag evidence <sessionId> --result 1 --json
-autorag feedback <sessionId> --useful 1,3 --not-useful 2 --json
-```
-
-- `evidence` shows the persisted source, retrieval method, stable evidence ID,
-  excerpt or content, and any `chunkIndex`, `lineNumber`, and
-  `retrievalResultId` behind a numbered result. Omit `--result` to inspect the
-  whole session.
-- `feedback` records numbered usefulness so retrieval memory can learn.
-  Numbers refer to the report's result numbers. Supply at least one feedback
-  list.
-- Preserve real source mapping and numbered identifiers end to end: retrieve
-  output feeds the report, the report's session feeds evidence and feedback.
-
-## Rules
-
-- Refresh before retrieval; refresh again when roots change.
-- Use only configured and approved search paths and datasources.
-- Never move, rename, edit, or delete source documents.
-- Never expose provider credentials or authentication payloads.
-- Treat report `source` values as opaque: persist them verbatim, never read
-  the filesystem through them.
-- Surface diagnostics and `unsearched` reasons to the user as written; they
-  carry the real error text needed to fix the failure.
-- Prefer `--json` whenever another agent consumes the output.