/**
 * Doc frontmatter schema, inference rules, and parser for the `/docs` index.
 *
 * Each markdown file under `docs/**` may declare a leading YAML frontmatter
 * block. All fields are optional; missing fields are inferred from the path,
 * the first `# H1`, and the `docs/site/site_doc_manifest.yaml` entries.
 *
 * Determinism: inference is a pure function of (relative path, raw markdown
 * source, manifest entries). No `Date.now()` / `Math.random()`.
 */
export type DocVisibility = "public" | "internal";
export type DocAudience = "developer" | "operator" | "agent" | "user";
export interface DocFrontmatter {
    /** Display title. Defaults to first H1, else humanized filename. */
    title: string;
    /** One-line summary. Defaults to first non-empty paragraph (truncated). */
    summary: string;
    /** Top-level category slug from `site_doc_manifest.yaml#categories`. */
    category: string;
    /** Optional subcategory slug. */
    subcategory: string | null;
    /** Sort order within (sub)category. Lower = earlier. Default 100. */
    order: number;
    /** Whether this doc is in the curated featured list. Display-only. */
    featured: boolean;
    /** Visibility gate. `internal` docs 404 unless show-internal env is set. */
    visibility: DocVisibility;
    /** Intended reader. */
    audience: DocAudience;
    /** Free-form tags for search. */
    tags: string[];
    /** ISO date (YYYY-MM-DD) of last human review; null when unknown. */
    last_reviewed: string | null;
    /** Marks the doc as deprecated. Hidden from the index by default; direct slug lookup still resolves. */
    deprecated: boolean;
    /** Optional slug of the doc that replaces this one. Surfaced in direct lookups. */
    superseded_by: string | null;
    /** Optional free-text reason for deprecation. */
    deprecation_reason: string | null;
}
export interface RawDocFrontmatter {
    title?: unknown;
    summary?: unknown;
    category?: unknown;
    subcategory?: unknown;
    order?: unknown;
    featured?: unknown;
    visibility?: unknown;
    audience?: unknown;
    tags?: unknown;
    last_reviewed?: unknown;
    deprecated?: unknown;
    superseded_by?: unknown;
    deprecation_reason?: unknown;
}
/** Strip a leading YAML frontmatter block. Returns the raw YAML and body. */
export declare function splitFrontmatter(source: string): {
    yaml: string | null;
    body: string;
};
/**
 * Minimal YAML scalar/list parser for the frontmatter shape we support.
 *
 * We do NOT take a dep on `gray-matter` for the v0 of this route: frontmatter
 * is restricted to flat key-value pairs with primitives or bracketed string
 * lists (`tags: [a, b, c]`). Anything more exotic falls back to undefined and
 * is filled by inference.
 */
export declare function parseFlatYaml(yaml: string): RawDocFrontmatter;
/** Folder → default category & visibility table. Single source of truth. */
export declare const FOLDER_DEFAULTS: ReadonlyArray<{
    prefix: string;
    category: string;
    subcategory?: string;
    visibility: DocVisibility;
    audience: DocAudience;
}>;
/** Match a `docs/`-relative path against `FOLDER_DEFAULTS`. */
export declare function resolveFolderDefaults(relPath: string): {
    category: string;
    subcategory: string | null;
    visibility: DocVisibility;
    audience: DocAudience;
};
/** Extract the first H1 from a markdown body. */
export declare function extractFirstH1(body: string): string | null;
/** Extract the first non-empty paragraph (after H1, capped at 240 chars). */
export declare function extractFirstParagraph(body: string): string | null;
/** Humanize a filename slug (`core_identity` → `Core Identity`). */
export declare function humanizeFilename(name: string): string;
/**
 * Fully resolve frontmatter for a doc. Pure function of inputs; deterministic.
 *
 * @param relPath  Path relative to `docs/` (POSIX, e.g. `architecture/architecture.md`).
 * @param source   Raw markdown source (frontmatter + body).
 * @param manifestEntry  Optional entry from `site_doc_manifest.yaml#entries`.
 */
export declare function resolveFrontmatter(relPath: string, source: string, manifestEntry?: {
    status?: string;
}): DocFrontmatter;
//# sourceMappingURL=doc_frontmatter.d.ts.map