/**
 * Shared documentation primitives. Consumed by the `now-sdk explain` CLI and by
 * runtime callers (e.g. agent tools) that scan, search, and read the markdown docs
 * bundled with the user's installed `@servicenow/sdk`. Callers
 * inject their own filesystem adapter (Node fs in the CLI, virtual fs in the
 * IDE/agent path).
 */
/** Documentation topic produced by `scanDocs`. */
export type DocFile = {
    /** Basename without `.md`. Unique across the docs tree. */
    name: string;
    /** Frontmatter tags. Empty when none. */
    tags: string[];
    /** First paragraph after the first heading via `extractSummary`. */
    summary: string;
    /** Absolute path to the markdown file. */
    filePath: string;
};
/**
 * Minimal Fs shape consumed by {@link scanDocs}.
 */
export interface DocsFs {
    readdirSync(path: string): string[];
    statSync(path: string): {
        isDirectory(): boolean;
    };
    readFileSync(path: string, encoding: 'utf-8'): string;
}
/**
 * Ranked match precision tiers.
 */
export type MatchTier = 'exact-name' | 'exact-tag' | 'plural-name' | 'plural-tag' | 'substring';
/**
 * Recursively walk a docs directory and return every `.md` file as a {@link DocFile}.
 * Topic name is the file's basename without `.md`. Throws on basename collision.
 * POSIX-style paths only.
 */
export declare function scanDocs(docsDir: string, fs: DocsFs): DocFile[];
/**
 * Parse `tags` from YAML frontmatter. Inline array form only (`tags: [a, b, c]`);
 * multi-line list syntax (tags:\n  - foo) is not supported.
 */
export declare function parseFrontmatter(content: string): {
    tags: string[];
    body: string;
};
/**
 * Extract the first paragraph after the first heading. Skips blanks and headings,
 * collects non-empty non-heading lines until a blank line or next heading.
 */
export declare function extractSummary(body: string): string;
/**
 * Match a topic against a search term and return the strongest tier, or null.
 */
export declare function matchDoc(topic: DocFile, searchTerm: string): MatchTier | null;
/**
 * Precise lookup: returns the highest-precision tier that has matches.
 * `exact-name` always returns a single topic; lower tiers may return multiple.
 */
export declare function findDocs(topics: DocFile[], searchTerm: string): DocFile[];
/**
 * Broad filter: returns every topic that matches at any tier including substring.
 */
export declare function filterDocs(topics: DocFile[], searchTerm: string): DocFile[];
/**
 * Singular/plural variants of a search term used as fallback matches.
 */
export declare function pluralVariants(term: string): string[];