import type { ToolResult } from "./tool-specs.js";
export { DOCS_VERSION } from "./docs-bundle.generated.js";
/** The categories the docs index lists pages under, in its order. */
export declare const DOCS_CATEGORIES: readonly ["Start here", "Guide", "Concept", "Reference", "Project"];
export type DocsCategory = (typeof DOCS_CATEGORIES)[number];
export interface DocsPage {
    /** URL-ish key, e.g. "architecture". Also the argument an agent passes as `page`. */
    slug: string;
    title: string;
    /** The page's classification line, e.g. "Concept (informative)" or "Reference". */
    kind: string;
    /** The category that line names, which the index lists the page under. The spec and lang are
     *  `normative`, and the schema is `reference`. */
    category: DocsCategory | "normative" | "reference";
    /** One-line summary for the index. */
    summary: string;
    /** Full Markdown. */
    body: string;
}
export interface DocsBundle {
    /** The installed Cotal version these docs are exact for, e.g. "0.10.1". */
    version: string;
    generatedFrom: string;
    pages: DocsPage[];
    /** The normative wire contract (SPEC.md). Reachable as page "spec". */
    spec: {
        title: string;
        body: string;
    };
    /** The normative workflow-language reference (spec/cotal-lang.md). Reachable as page "lang". */
    lang: {
        title: string;
        body: string;
    };
    /** The machine-readable message schema (JSON). Reachable as page "schema". */
    schema: {
        title: string;
        body: string;
    };
}
/** Index fields generated from the same sources, without the page bodies. */
export interface DocsMetadata {
    version: string;
    pages: Omit<DocsPage, "body">[];
    spec: {
        title: string;
    };
    lang: {
        title: string;
    };
    schema: {
        title: string;
    };
}
/** The index: version banner + every page (slug · kind · summary) + spec/schema + how to
 *  go deeper. Cheap orientation an agent reads before answering anything about Cotal. */
export declare function renderDocsIndex(): string;
export interface DocHit {
    /** Page slug to fetch in full via cotal_docs(page: slug). */
    slug: string;
    pageTitle: string;
    heading: string;
    /** The matching section's Markdown. */
    text: string;
    score: number;
}
/** BM25 search over heading-aware sections. Returns the best-matching sections (at most two per
 *  page, for diversity), each with a pointer to read the full page. Offline; no embeddings. */
export declare function searchDocs(query: string, limit?: number): DocHit[];
/** Cap a section so a single long match can't blow the context; the pointer covers the rest. */
export declare function capSection(text: string, maxLines?: number): string;
/** Why a refresh served the bundle: the version-pinned path answered with no page, or did not answer. */
type RemoteMiss = "not-published" | "unreachable";
/** One page as read: the bundled copy, or with `refresh` the version-pinned copy from docs.cotal.ai
 *  when that path serves one. `refresh` says what the remote pass did, or null when none was asked. */
export interface DocsPageRead {
    readonly version: string;
    readonly page: DocsPage;
    readonly source: "bundled" | "docs.cotal.ai";
    readonly refresh: "served" | RemoteMiss | null;
}
/**
 * Read one page. `refresh` fetches the IMMUTABLE, version-pinned path
 * (docs.cotal.ai/v/<installed-version>/…): a 200 body provably belongs to the installed
 * version, so there is no separate version check to race or skew against. When that path is
 * absent (version-pinned docs aren't published yet) or unreachable, the version-exact bundle is
 * served. Fail-closed: an unverifiable remote is never served. Undefined for an unknown page.
 */
export declare function readDocsPage(page: string, opts?: {
    refresh?: boolean;
}): Promise<DocsPageRead | undefined>;
/** The bundled docs' version, their normative sources and their pages, for an index, the pages in
 *  the order of their categories. */
export declare function docsIndex(): {
    version: string;
    sources: {
        slug: string;
        title: string;
    }[];
    pages: Omit<DocsPage, "body">[];
};
export interface DocsArgs {
    page?: string;
    query?: string;
    refresh?: boolean;
}
/** The `cotal_docs` tool body. Pure over the bundle except for the opt-in remote refresh. */
export declare function runDocs(args: DocsArgs): Promise<ToolResult>;
//# sourceMappingURL=docs.d.ts.map