datanotes 2.0.0 → 3.0.0

package/dist/api/catalog.d.cts

@@ -0,0 +1,69 @@
+/**
+ * The operations of the HTTP API, described for their callers: name, description, input schema
+ * and hints. The MCP server (`datanotes mcp`, src/mcp) offers each one as a tool of the same name
+ * (the shape is MCP's tool definition); the OpenAPI document and the docs are generated from it. The route and body each
+ * one sends: `requests.ts`.
+ */
+export interface OperationDef {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /**
+     * MCP tool hints (not part of the Datanotes 3 contract). `destructiveHint` is true for every
+     * write that may overwrite or remove existing data (values, names, definitions, settings, history)
+     * or send it out of the engine (webhooks); false only for reads and purely additive writes
+     * (tests/api-mcp.test.ts holds the list).
+     */
+    annotations: {
+        title?: string;
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /** JSON Schema of the successful (2xx) response body, for the OpenAPI document; not sent to MCP clients. */
+    responseSchema?: Record<string, unknown>;
+    /**
+     * Secrets in the call: the argument names and result keys never recorded (the change feed's
+     * `tool_call` events, which the store backup commits). `redactToolCall` (redact.ts) applies it.
+     */
+    sensitive?: {
+        args?: string[];
+        result?: string[];
+    };
+}
+export declare const OPERATIONS: OperationDef[];
+/**
+ * The kinds of operation, as the docs' reference groups them (one page each,
+ * `reference/operations/<kind>`), like the statement kinds of a SQL reference.
+ */
+export declare const OPERATION_KINDS: {
+    readonly schema: {
+        readonly title: "Schema operations (DDL)";
+        readonly label: "Schema (DDL)";
+        readonly description: "Operations that define the database: tables, columns, constraints, bases and views.";
+    };
+    readonly rows: {
+        readonly title: "Row operations (DML)";
+        readonly label: "Rows (DML)";
+        readonly description: "Operations that write rows: insert, update, merge, delete, move, adopt and batch.";
+    };
+    readonly queries: {
+        readonly title: "Query operations";
+        readonly label: "Queries";
+        readonly description: "Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph.";
+    };
+    readonly history: {
+        readonly title: "History operations";
+        readonly label: "History";
+        readonly description: "Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.";
+    };
+    readonly auxiliary: {
+        readonly title: "Auxiliary operations";
+        readonly label: "Auxiliary";
+        readonly description: "Operations that describe and check the database, configure it and maintain its indexes.";
+    };
+};
+export type OperationKind = keyof typeof OPERATION_KINDS;
+/** The kind of every operation of {@link OPERATIONS} (tests/operation-kinds.test.ts: each has exactly one). */
+export declare const OPERATION_KIND: Readonly<Record<string, OperationKind>>;

package/dist/api/catalog.d.ts

@@ -1,13 +1,19 @@
 /**
  * The operations of the HTTP API, described for their callers: name, description, input schema
- * and hints. An MCP server offers each one as a tool of the same name (the shape is MCP's tool
- * definition); the OpenAPI document and the docs are generated from it. The route and body each
+ * and hints. The MCP server (`datanotes mcp`, src/mcp) offers each one as a tool of the same name
+ * (the shape is MCP's tool definition); the OpenAPI document and the docs are generated from it. The route and body each
  * one sends: `requests.ts`.
  */
 export interface OperationDef {
     name: string;
     description: string;
     inputSchema: Record<string, unknown>;
+    /**
+     * MCP tool hints (not part of the Datanotes 3 contract). `destructiveHint` is true for every
+     * write that may overwrite or remove existing data (values, names, definitions, settings, history)
+     * or send it out of the engine (webhooks); false only for reads and purely additive writes
+     * (tests/api-mcp.test.ts holds the list).
+     */
     annotations: {
         title?: string;
         readOnlyHint?: boolean;
@@ -17,5 +23,47 @@ export interface OperationDef {
     };
     /** JSON Schema of the successful (2xx) response body, for the OpenAPI document; not sent to MCP clients. */
     responseSchema?: Record<string, unknown>;
+    /**
+     * Secrets in the call: the argument names and result keys never recorded (the change feed's
+     * `tool_call` events, which the store backup commits). `redactToolCall` (redact.ts) applies it.
+     */
+    sensitive?: {
+        args?: string[];
+        result?: string[];
+    };
 }
 export declare const OPERATIONS: OperationDef[];
+/**
+ * The kinds of operation, as the docs' reference groups them (one page each,
+ * `reference/operations/<kind>`), like the statement kinds of a SQL reference.
+ */
+export declare const OPERATION_KINDS: {
+    readonly schema: {
+        readonly title: "Schema operations (DDL)";
+        readonly label: "Schema (DDL)";
+        readonly description: "Operations that define the database: tables, columns, constraints, bases and views.";
+    };
+    readonly rows: {
+        readonly title: "Row operations (DML)";
+        readonly label: "Rows (DML)";
+        readonly description: "Operations that write rows: insert, update, merge, delete, move, adopt and batch.";
+    };
+    readonly queries: {
+        readonly title: "Query operations";
+        readonly label: "Queries";
+        readonly description: "Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph.";
+    };
+    readonly history: {
+        readonly title: "History operations";
+        readonly label: "History";
+        readonly description: "Operations on the journal, a table's versions, the change feed and webhooks: undo, time travel, restore and vacuum.";
+    };
+    readonly auxiliary: {
+        readonly title: "Auxiliary operations";
+        readonly label: "Auxiliary";
+        readonly description: "Operations that describe and check the database, configure it and maintain its indexes.";
+    };
+};
+export type OperationKind = keyof typeof OPERATION_KINDS;
+/** The kind of every operation of {@link OPERATIONS} (tests/operation-kinds.test.ts: each has exactly one). */
+export declare const OPERATION_KIND: Readonly<Record<string, OperationKind>>;

package/dist/api/cli-options.d.cts

@@ -0,0 +1,39 @@
+/**
+ * The command line options of the `datanotes` commands: `--name value` or `--name=value` for an
+ * option with a value, `--name` for a flag. An option the command does not know is refused with
+ * the closest one, so a typo never runs a command with its defaults.
+ */
+export interface OptionSpec {
+    /** Options that take a value. */
+    values?: readonly string[];
+    /** Options that take none. */
+    flags?: readonly string[];
+}
+/** A command line the command cannot run: what is wrong, and how to write it. */
+export declare class CliOptionError extends Error {
+    readonly hint: string;
+    readonly name = "CliOptionError";
+    /** Every command and its options. */
+    readonly docs = "https://datanotes.dev/reference/cli.md";
+    constructor(message: string, hint: string);
+}
+export interface Options {
+    /** The value of an option, when given. */
+    get(name: string): string | undefined;
+    /** Was a flag given? */
+    has(name: string): boolean;
+}
+/** Read `argv` against what `command` takes; throws {@link CliOptionError} on anything else. */
+export declare function readOptions(argv: readonly string[], spec: OptionSpec, command: string): Options;
+/** The folder a command works on, and how to read it. */
+export interface FolderArg {
+    folder: string;
+    /** `--database`: the folder is the database (metastore.yaml at its root); else a vault holding it. */
+    atRoot: boolean;
+}
+/**
+ * The folder of `--database` (the folder is the database) or `--vault` (a vault holding the
+ * database in a subfolder), else DATANOTES_DATABASE or DATANOTES_VAULT: one of the two, never
+ * both. Null when none is given and the command can do without (`required` false).
+ */
+export declare function folderArg(o: Options, env: Record<string, string | undefined>, command: string, required?: boolean): FolderArg | null;

package/dist/api/cli-options.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The command line options of the `datanotes` commands: `--name value` or `--name=value` for an
+ * option with a value, `--name` for a flag. An option the command does not know is refused with
+ * the closest one, so a typo never runs a command with its defaults.
+ */
+export interface OptionSpec {
+    /** Options that take a value. */
+    values?: readonly string[];
+    /** Options that take none. */
+    flags?: readonly string[];
+}
+/** A command line the command cannot run: what is wrong, and how to write it. */
+export declare class CliOptionError extends Error {
+    readonly hint: string;
+    readonly name = "CliOptionError";
+    /** Every command and its options. */
+    readonly docs = "https://datanotes.dev/reference/cli.md";
+    constructor(message: string, hint: string);
+}
+export interface Options {
+    /** The value of an option, when given. */
+    get(name: string): string | undefined;
+    /** Was a flag given? */
+    has(name: string): boolean;
+}
+/** Read `argv` against what `command` takes; throws {@link CliOptionError} on anything else. */
+export declare function readOptions(argv: readonly string[], spec: OptionSpec, command: string): Options;
+/** The folder a command works on, and how to read it. */
+export interface FolderArg {
+    folder: string;
+    /** `--database`: the folder is the database (metastore.yaml at its root); else a vault holding it. */
+    atRoot: boolean;
+}
+/**
+ * The folder of `--database` (the folder is the database) or `--vault` (a vault holding the
+ * database in a subfolder), else DATANOTES_DATABASE or DATANOTES_VAULT: one of the two, never
+ * both. Null when none is given and the command can do without (`required` false).
+ */
+export declare function folderArg(o: Options, env: Record<string, string | undefined>, command: string, required?: boolean): FolderArg | null;

package/dist/api/client.d.cts

@@ -0,0 +1,89 @@
+/**
+ * A client of the Datanotes HTTP API, with no dependency: it runs in Node, in browsers and in
+ * Obsidian (pass Obsidian's `requestUrl` as the transport). `call` runs an operation of the
+ * catalogue by name, the way agents name them; `request` reaches any route.
+ */
+import { type OperationResult } from "./results.cjs";
+import { type Guidance } from "./guidance.cjs";
+export interface HttpRequest {
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface HttpResponse {
+    status: number;
+    text: string;
+}
+export type Transport = (req: HttpRequest) => Promise<HttpResponse>;
+/** Who is calling, recorded with every write (header `X-Datanotes-Actor`). Self-reported. */
+export interface ActorInfo {
+    /** The program: "claude-code", "cursor", a program's own name. */
+    harness?: string;
+    harness_version?: string;
+    model?: string;
+    /** The agent's session (the engine remembers the model an MCP server reports for it). */
+    session?: string;
+    /** The tool the agent called, when the call comes from an MCP server. */
+    tool?: string;
+}
+export declare const ACTOR_HEADER = "X-Datanotes-Actor";
+export declare class DatanotesError extends Error {
+    readonly kind: "unreachable" | "auth" | "http";
+    readonly status: number;
+    readonly name = "DatanotesError";
+    /** How to fix it, and where to read more (also at the end of the message). */
+    readonly hint?: string;
+    readonly docs?: string;
+    /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
+    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number, guidance?: Guidance | null);
+}
+export interface ClientOptions {
+    /** The engine's address, e.g. `http://127.0.0.1:27150`. */
+    url: string;
+    token: string;
+    /** Recorded with every write unless a call names another actor. */
+    actor?: ActorInfo;
+    transport?: Transport;
+}
+/** One tool call by an agent (an engine operation, or a tool of the MCP server's own), for the engine's change feed. */
+export interface ToolCallRecord {
+    tool: string;
+    args: Record<string, unknown>;
+    ok: boolean;
+    duration_ms: number;
+    value: unknown;
+    /** Who served it: "engine", or the name of the MCP server whose own tool it is. */
+    served_by: string;
+    session?: string;
+    result_chars?: number;
+    result_tokens?: number;
+}
+export declare const fetchTransport: Transport;
+export declare class DatanotesClient {
+    private readonly o;
+    readonly url: string;
+    private readonly send;
+    constructor(o: ClientOptions);
+    /** Send a request; the answer's status, its JSON (when it is JSON) and its text. */
+    request(method: "GET" | "POST", path: string, body?: unknown, opts?: {
+        actor?: ActorInfo;
+        accept?: string;
+    }): Promise<{
+        status: number;
+        json: unknown;
+        text: string;
+    }>;
+    /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
+    post<T = unknown>(route: string, body?: unknown, actor?: ActorInfo): Promise<T>;
+    /**
+     * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+     * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
+     * with the same message the engine gives.
+     */
+    call(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult>;
+    /** True when the engine answers `GET /` (no token needed). */
+    ping(): Promise<boolean>;
+    /** Record an agent's tool call in the change feed (what MCP servers report). */
+    recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<void>;
+}

package/dist/api/client.d.ts

@@ -3,8 +3,8 @@
  * Obsidian (pass Obsidian's `requestUrl` as the transport). `call` runs an operation of the
  * catalogue by name, the way agents name them; `request` reaches any route.
  */
-import { type OperationResult } from "./results";
-import type { OperationDef } from "./catalog";
+import { type OperationResult } from "./results.js";
+import { type Guidance } from "./guidance.js";
 export interface HttpRequest {
     url: string;
     method: "GET" | "POST";
@@ -18,11 +18,11 @@ export interface HttpResponse {
 export type Transport = (req: HttpRequest) => Promise<HttpResponse>;
 /** Who is calling, recorded with every write (header `X-Datanotes-Actor`). Self-reported. */
 export interface ActorInfo {
-    /** The program: "claude-code", "cursor", an app's name. */
+    /** The program: "claude-code", "cursor", a program's own name. */
     harness?: string;
     harness_version?: string;
     model?: string;
-    /** The agent's session (the engine remembers the model an app reports for it). */
+    /** The agent's session (the engine remembers the model an MCP server reports for it). */
     session?: string;
     /** The tool the agent called, when the call comes from an MCP server. */
     tool?: string;
@@ -32,8 +32,11 @@ export declare class DatanotesError extends Error {
     readonly kind: "unreachable" | "auth" | "http";
     readonly status: number;
     readonly name = "DatanotesError";
+    /** How to fix it, and where to read more (also at the end of the message). */
+    readonly hint?: string;
+    readonly docs?: string;
     /** `unreachable`: the engine did not answer; `auth`: the token was refused. */
-    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number);
+    constructor(message: string, kind?: "unreachable" | "auth" | "http", status?: number, guidance?: Guidance | null);
 }
 export interface ClientOptions {
     /** The engine's address, e.g. `http://127.0.0.1:27150`. */
@@ -43,23 +46,18 @@ export interface ClientOptions {
     actor?: ActorInfo;
     transport?: Transport;
 }
-/** A tool of a registered app, as `GET /datanotes/apps/tools/` lists it. */
-export interface AppTool extends Omit<OperationDef, "annotations"> {
-    annotations?: OperationDef["annotations"];
-    app: string;
-}
-/** One call of an operation or an app tool by an agent, for the engine's change feed. */
+/** One tool call by an agent (an engine operation, or a tool of the MCP server's own), for the engine's change feed. */
 export interface ToolCallRecord {
     tool: string;
     args: Record<string, unknown>;
     ok: boolean;
-    durationMs: number;
+    duration_ms: number;
     value: unknown;
-    /** Who served it: "engine" or the app's name. */
-    servedBy: string;
+    /** Who served it: "engine", or the name of the MCP server whose own tool it is. */
+    served_by: string;
     session?: string;
-    resultChars?: number;
-    resultTokens?: number;
+    result_chars?: number;
+    result_tokens?: number;
 }
 export declare const fetchTransport: Transport;
 export declare class DatanotesClient {
@@ -78,23 +76,14 @@ export declare class DatanotesClient {
     }>;
     /** `POST /datanotes/<route>` and its JSON answer; throws on an error status. */
     post<T = unknown>(route: string, body?: unknown, actor?: ActorInfo): Promise<T>;
-    /** Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments. */
+    /**
+     * Run an operation of the catalogue (`select_rows`, `insert_row`, …) with an agent's arguments.
+     * Arguments the operation does not take, or of the wrong type, are refused before anything is sent,
+     * with the same message the engine gives.
+     */
     call(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult>;
-    /** Run an operation of the engine, or else a registered app's tool of that name. */
-    invoke(name: string, args?: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult & {
-        servedBy: string;
-    }>;
     /** True when the engine answers `GET /` (no token needed). */
     ping(): Promise<boolean>;
-    /** The tools of the registered apps and the apps' instructions for agents. */
-    appTools(): Promise<{
-        tools: AppTool[];
-        instructions: string;
-    }>;
-    /** Call an app's tool through the engine (which holds the app's credentials). */
-    callAppTool(name: string, args: Record<string, unknown>, actor?: ActorInfo): Promise<OperationResult & {
-        servedBy: string;
-    }>;
     /** Record an agent's tool call in the change feed (what MCP servers report). */
     recordToolCall(call: ToolCallRecord, actor?: ActorInfo): Promise<void>;
 }

package/dist/api/docs.d.cts

@@ -0,0 +1,211 @@
+/**
+ * The documentation of this version of Datanotes, read offline: every page of datanotes.dev as
+ * Markdown, shipped in the npm package as `dist/docs/` (scripts/copy-docs.mjs copies them there
+ * after the docs build). The MCP server `datanotes mcp` serves it to agents as three tools
+ * (`list_docs`, `read_docs`, `search_docs`: src/api/mcp.ts), the engine to programs as
+ * `GET /datanotes/manual/<page>.md` (src/server/http-server.ts). They are not engine operations:
+ * nothing is journaled and no engine is needed.
+ *
+ * A page is named by its path on the site without `.md` (`guides/read-and-write/read-and-filter`), a section by the
+ * anchor of its heading (`guides/read-and-write/read-and-filter#compare-values-with-operators`), as on the site; the
+ * site's own addresses (`https://datanotes.dev/guides/read-and-write/read-and-filter/#…`) are read too. Every mistake
+ * says what is wrong, the closest real page or section, and how to list them (the hint standard
+ * of src/api/guidance.ts).
+ */
+import { type Guidance } from "./guidance.cjs";
+/** An environment variable that names the folder of the docs instead of the package's own. */
+export declare const DOCS_DIR_ENV = "DATANOTES_DOCS_DIR";
+/** The most characters read_docs returns at once: about 5 000 tokens. */
+export declare const READ_DOCS_MAX = 20000;
+/** The page for agents on reading the docs offline. */
+export declare const OFFLINE_DOCS = "https://datanotes.dev/guides/agents/docs-offline.md#the-agent-reads-the-docs-of-its-version";
+/** A mistake in reading the docs: what is wrong, how to fix it, where to read more. */
+export declare class DocsError extends Error {
+    readonly hint: string;
+    readonly docs: string;
+    /** `missing`: the docs are not in this installation; `not_found`: no such page or section; `bad_input`: wrong arguments. */
+    readonly code: "missing" | "not_found" | "bad_input";
+    constructor(message: string, g: Guidance, code: DocsError["code"]);
+}
+/** A page of the docs. */
+export interface DocsPage {
+    /** Its path on the site, without `.md`: `guides/read-and-write/read-and-filter` (the home page is `index`). */
+    path: string;
+    title: string;
+    description: string;
+}
+/** How a section matched a search: by its words (BM25), or by its meaning (the engine's vector index of the docs). */
+export type DocsSignal = "keyword" | "semantic";
+/** A section of a page that matches a search. */
+export interface DocsHit {
+    /** What read_docs reads: `guides/read-and-write/read-and-filter#compare-values-with-operators` (the page alone for its introduction). */
+    path: string;
+    page: string;
+    section: string;
+    excerpt: string;
+    /** BM25 for a keyword search; the Reciprocal Rank Fusion score for a hybrid one. */
+    score: number;
+    /** The rankings the section is in: `keyword` alone without semantic search. */
+    signals: DocsSignal[];
+}
+/** A section as search_docs ranks it, with the text the engine embeds for semantic search. */
+export interface DocsSection {
+    /** What read_docs reads, as in {@link DocsHit}. */
+    path: string;
+    page: string;
+    section: string;
+    /** The page's title and the heading, then the section's own prose, then its code. */
+    text: string;
+}
+interface Section {
+    anchor: string;
+    title: string;
+    level: number;
+    /** Where its heading starts, where it ends with its subsections, and where its own text ends. */
+    start: number;
+    end: number;
+    ownEnd: number;
+}
+interface Page extends DocsPage {
+    text: string;
+    sections: Section[];
+}
+/**
+ * The folder of the docs: `DATANOTES_DOCS_DIR` when set, else the package's `dist/docs` (next to
+ * `dist/datanotes.cjs`, above `dist/api/`, or in a checkout where the docs were built). Null when
+ * there is none.
+ */
+export declare function findDocsDir(env?: Record<string, string | undefined>, from?: string): string | null;
+/** A heading's anchor as the site makes it (github-slugger): lowercase, punctuation dropped, spaces as dashes. */
+export declare function slug(heading: string): string;
+/** A page or section as given (`guides/read-and-write/read-and-filter.md`, `/guides/read-and-write/read-and-filter/#x`, a datanotes.dev address): the page's path and the anchor. */
+export declare function docsRef(input: string): {
+    page: string;
+    anchor: string | null;
+};
+/** Common English words left out of queries and texts: they say nothing of the topic. */
+export declare const STOP_WORDS: ReadonlySet<string>;
+/**
+ * The stem of a lowercase word: plurals and verb endings stripped, so that the forms of a word meet
+ * (`tables`/`table`, `queries`/`query`, `renamed`/`renaming`/`rename`, `dropped`/`drop`,
+ * `rated`/`rate`, `using`/`use`). Not a dictionary form (`create` is `creat`), only the same for
+ * every form. Words of three letters or less, and words with digits, stay as they are.
+ */
+export declare function stem(word: string): string;
+/** The search terms of a text: folded words, without one-letter and common words, stemmed. */
+export declare function tokenize(text: string): string[];
+/**
+ * Words that mean the same thing in these docs, for queries: a word of the query also matches the
+ * others of its group, with SYNONYM_WEIGHT. An entry can be a phrase ("roll back"), which matches
+ * where its words follow each other, in the query and in the docs.
+ */
+export declare const SEARCH_SYNONYMS: readonly (readonly string[])[];
+/** How much a synonym counts against the word itself. */
+export declare const SYNONYM_WEIGHT = 0.7;
+/** A term of a query: the word (or synonym phrase) as stems, and every way it matches, itself first. */
+export interface QueryTerm {
+    term: string;
+    alternatives: {
+        stems: string[];
+        weight: number;
+    }[];
+}
+/**
+ * The terms of a query, each with its synonyms. A synonym phrase written in the query ("roll
+ * back", "time travel") is one term; a term repeated in the query counts once.
+ */
+export declare function queryTerms(query: string): QueryTerm[];
+/** A query of search_docs as written: the words to rank by, and the words a section must hold or must not. */
+export interface DocsQuery {
+    /** The words to rank by, the syntax taken out: `"time travel" +view -sql` ranks by `time travel view`. */
+    text: string;
+    /** Quoted phrases and +terms, as stems: each must appear in a section (its words in a row, in any form). */
+    required: string[][];
+    /** -terms and -"phrases", as stems: a section that holds one is left out. */
+    excluded: string[][];
+}
+/**
+ * Read the syntax of a search_docs query: `"a phrase"` and `+term` must appear in a section,
+ * `-term` (or `-"a phrase"`) must not, every other word ranks only. Curly quotes count as straight
+ * ones, a quote left open runs to the end, and a word that starts with two dashes (`--vault`) is a
+ * word. Words that say nothing (`+the`) require nothing.
+ */
+export declare function parseQuery(query: string): DocsQuery;
+/** The docs in a folder (null: there are none, and every call says how to get them). */
+export declare class DocsLibrary {
+    readonly dir: string | null;
+    private loaded;
+    private index;
+    private hash;
+    private sectionList;
+    constructor(dir: string | null);
+    private missing;
+    private all;
+    /** The pages, sorted by path; only those under `prefix` (`guides/`) when it is given. */
+    list(prefix?: string): DocsPage[];
+    private page;
+    private section;
+    /**
+     * The Markdown of a page (`guides/read-and-write/read-and-filter`) or of one section (`guides/read-and-write/read-and-filter#anchor`, or
+     * `section`), with its subsections. Without a cap, the whole text.
+     */
+    text(ref: string, section?: string | null): {
+        ref: string;
+        text: string;
+        page: Page;
+        from: number;
+    };
+    /**
+     * What read_docs returns: the page or section from `offset`, at most `max` characters, cut at the
+     * end of a line, then a note on how to read the rest (the sections that follow, or the offset).
+     */
+    read(ref: string, opts?: {
+        section?: string | null;
+        offset?: number;
+        max?: number;
+    }): string;
+    private searchIndex;
+    /** The terms of a query to rank by; a query with none is refused. */
+    private termsOf;
+    /**
+     * The units ranked by BM25 for the query's words, best first, without those the required and
+     * excluded words leave out. Each term of the query (a word in any form, or one of its synonyms)
+     * scores by BM25 in a section's text, and more in its heading and its page's title; rare terms
+     * count more than common ones; a heading with every term, and terms next to each other as in
+     * the query, add to it; a section with every term ranks above one with some.
+     */
+    private ranked;
+    /**
+     * The sections that best match `query`, best first, by their words (BM25: {@link ranked}). A
+     * quoted phrase or a +term must appear in a section, a -term must not (parseQuery).
+     */
+    search(query: string, limit?: number): DocsHit[];
+    /**
+     * Hybrid search: the ranking of {@link search} by words, and `semantic`, the sections ranked by
+     * meaning (the engine's vector index of these docs, best first), fused by Reciprocal Rank
+     * Fusion: a section scores the sum of 1 / (RRF_K + its rank) over the rankings it is in, among
+     * the first FUSION_DEPTH of each. The required and excluded words filter both rankings, and a
+     * section these docs do not have is left out. Each hit says which rankings it is in (`signals`).
+     */
+    hybrid(query: string, semantic: readonly {
+        path: string;
+    }[], limit?: number): DocsHit[];
+    /**
+     * Every section as search_docs ranks them (a page's introduction too), with the text to embed
+     * for semantic search: the page's title and the heading, the prose, then the code.
+     */
+    sections(): readonly DocsSection[];
+    /**
+     * The version of these docs: a hash of their sections (paths and texts). The engine's vector
+     * index of the docs is rebuilt when it changes, and search_docs fuses its ranking only when the
+     * engine's docs have the same version as its own.
+     */
+    version(): string;
+}
+/** The constant of Reciprocal Rank Fusion: 60, the value of its paper (Cormack et al., 2009) and of most search engines; it keeps the first ranks from outweighing agreement between the rankings. */
+export declare const RRF_K = 60;
+/** How many sections of each ranking hybrid search fuses. */
+export declare const FUSION_DEPTH = 50;
+/** The docs of a folder (default: `findDocsDir()`), loaded once per folder. */
+export declare function openDocs(dir?: string | null): DocsLibrary;
+export {};