import type { ProjectType } from '../discovery/types.js';
import { type DocCategory, type DocEntry, type SearchIndex, type SearchResult } from './types.js';
/**
 * The canonical list of documentation categories, in a stable display order.
 * Exported so the CLI and MCP surfaces validate against a single source of truth
 * instead of maintaining their own copies. Derived from {@link CATEGORY_TAXONOMY}.
 */
export declare const DOC_CATEGORIES: readonly DocCategory[];
/**
 * Parses and validates a user-supplied set of documentation categories into a
 * "topics" allowlist that bounds the entire available corpus (see
 * {@link SearchDocsOptions.enabledCategories}). Accepts a comma-separated string
 * or an array; names are trimmed and lower-cased.
 *
 * Unknown names are dropped (and reported via `onInvalid`, if provided). Returns
 * `undefined` when the input is empty or contains no valid categories, which
 * means "no restriction" — matching the tolerant behavior of the MCP `--toolsets`
 * flag, so a typo yields a warning and the full corpus rather than a dead tool.
 *
 * @param input - Comma-separated category names, or an array of names
 * @param onInvalid - Optional callback invoked with any unrecognized names
 * @returns The validated, de-duplicated categories, or `undefined` for no restriction
 */
export declare function resolveEnabledCategories(input: string | readonly string[] | undefined, onInvalid?: (invalid: string[]) => void): DocCategory[] | undefined;
/**
 * Computes the set of doc categories relevant to the given workspace marker(s):
 * the always-relevant categories plus the union of each marker's categories
 * (merged, not summed).
 */
export declare function categoriesForWorkspace(workspace: ProjectType | ProjectType[]): DocCategory[];
/**
 * Loads the combined search index from every bundled corpus directory.
 *
 * Combines the Script API reference, standard job steps, Developer Center
 * guides, and this project's own docs so all are searchable through the same
 * functions. Corpora that have not been generated are skipped.
 *
 * @returns The combined search index with all documentation entries
 */
export declare function loadSearchIndex(): SearchIndex;
/**
 * Options for {@link searchDocs}.
 */
export interface SearchDocsOptions {
    /** Maximum number of results to return (default: 20). */
    limit?: number;
    /** Restrict results to one or more corpora/categories (hard filter). */
    category?: DocCategory | DocCategory[];
    /**
     * The current workspace marker(s) (e.g. from workspace detection). When set,
     * the categories relevant to those markers rank higher (always a boost — never
     * hides anything). To hard-scope instead, use {@link SearchDocsOptions.category}
     * or {@link SearchDocsOptions.enabledCategories}.
     */
    workspace?: ProjectType | ProjectType[];
    /**
     * A hard allowlist of categories that bounds the ENTIRE available corpus for
     * this call — a configuration boundary, distinct from the per-query
     * {@link SearchDocsOptions.category} filter and the soft workspace boost.
     *
     * When set, only entries in these categories are ever eligible; any `category`
     * narrows *within* this set (their intersection wins). Intended to be resolved
     * once from a launch-time flag/env var (see {@link resolveEnabledCategories}) so
     * operators can pin the docs surface to exactly the topics they want exposed.
     * `undefined` means no restriction.
     */
    enabledCategories?: readonly DocCategory[];
}
/**
 * Searches the combined documentation index.
 *
 * Higher scores are better. Results carry the full {@link DocEntry} (including
 * `category`, `summary`, `keywords`, and `url` when available) so callers can
 * triage matches without a follow-up read.
 *
 * When `workspace` is provided, the categories relevant to those markers (e.g.
 * `sfra` for an SFRA project, `script-api`/`job-step` for any cartridge project,
 * `pwa-kit-managed-runtime`/`commerce-api` for PWA Kit, `sfnext`/`commerce-api`
 * for Storefront Next — plus the always-relevant docs) are boosted. It only ever
 * reorders results; use `category`/`enabledCategories` to hard-scope.
 *
 * @param query - The search query string
 * @param limitOrOptions - Result limit (number) or {@link SearchDocsOptions}
 * @returns Array of search results sorted by relevance (best first)
 *
 * @example
 * ```typescript
 * // Favor the current workspace's docs (nothing hidden)
 * searchDocs('deploy bundle', {workspace: 'pwa-kit-v3'});
 * // Hard-scope to one category instead
 * searchDocs('components', {category: 'sfnext'});
 * ```
 */
export declare function searchDocs(query: string, limitOrOptions?: number | SearchDocsOptions): SearchResult[];
/**
 * Lists documentation entries, optionally filtered by category.
 *
 * @param category - Optional corpus/category (or list) to restrict to
 * @param enabledCategories - Optional launch-time allowlist that bounds the
 *   entire corpus (see {@link SearchDocsOptions.enabledCategories}). When set,
 *   only entries in these categories are eligible; `category` narrows within it.
 * @returns Array of matching documentation entries
 */
export declare function listDocs(category?: DocCategory | DocCategory[], enabledCategories?: readonly DocCategory[]): DocEntry[];
/**
 * Reads the full content of a documentation entry by its exact id.
 *
 * Bundled entries are read from disk. Entries whose content is published online
 * (Developer Center guides) are fetched from their canonical URL; on network
 * failure a readable fallback assembled from the indexed metadata is returned.
 *
 * @param id - The documentation id
 * @returns The document content (markdown)
 * @throws Error if the id is unknown
 */
export declare function readDoc(id: string): Promise<string>;
/**
 * Reads the content of a resolved {@link DocEntry}, choosing bundled-file vs.
 * online fetch based on whether the entry ships its content on disk.
 */
export declare function readEntryContent(entry: DocEntry): Promise<string>;
/**
 * Reads documentation by fuzzy-matching the query and returning the best match.
 *
 * @param query - The search query string
 * @param options - Optional search constraints (e.g. category)
 * @returns The best matching entry and its content, or null if no match
 *
 * @example
 * ```typescript
 * const doc = await readDocByQuery('ProductMgr');
 * if (doc) console.log(doc.content);
 * ```
 */
export declare function readDocByQuery(query: string, options?: SearchDocsOptions): Promise<{
    entry: DocEntry;
    content: string;
} | null>;
/**
 * Resets the in-memory index/search caches. Intended for tests that swap the
 * bundled data on disk between assertions.
 */
export declare function resetDocsCache(): void;