export type Step = {
    slug: string;
    file: string;
    head: string;
    desc: string;
};
/** Where a page may be read. `public` reaches the public docs site; `possession`
 *  reaches customers only inside the image they already run. PUBLIC is the
 *  default and no page is special-cased -- a candid limitations page is a trust
 *  asset, and hiding the honest page is an odd signal to an evaluator (fleet
 *  review 03 open question 3). Turnkey privacy is a repo/bundle-level
 *  guarantee, never this field. */
export type PageVisibility = "public" | "possession";
export type ManualPage = {
    id: string;
    nav: string;
    title: string;
    kind: "fn" | "ex";
    tag?: string;
    intro: string;
    steps: Step[];
    links: string[];
    thin?: boolean;
    /** Overrides the bundle's visibility for this page alone. */
    visibility?: PageVisibility;
};
export interface ManualOverview {
    /** The overview <h1>. */
    headline: string;
    /** The lead paragraph under it. */
    lead: string;
    /** The hero capture (a representative shot) and its caption. A prose-only
     *  manual (a turnkey handover) has none. */
    hero?: {
        slug: string;
        file: string;
        alt: string;
        caption: string;
    };
    /** Left column heading of the two-up index. Default "By function". */
    byFunctionHeading?: string;
    /** Right column heading. Default "By example". */
    byExampleHeading?: string;
    /** The small print under the right column heading. */
    byExampleIntro: string;
}
/** A way out of the manual: the product's marketing page, the platform docs,
 *  a contact. Rendered in the footer of every export. Hash links are the only
 *  navigation otherwise, so a manual without these is a cul-de-sac. */
export interface ManualLink {
    label: string;
    href: string;
}
/** A prose page: hand-written markdown carried as-is (a turnkey's handover
 *  document, an operator runbook). Rendered to HTML in the manual, verbatim in
 *  the bundle. Captures are optional per page; a document has none. */
export interface ManualDocument {
    id: string;
    nav: string;
    title: string;
    markdown: string;
    /** Overrides the bundle's visibility for this page alone. */
    visibility?: PageVisibility;
}
export interface ManualSpec {
    /** Sidebar wordmark + document brand. */
    brand: string;
    /** The full <title> for both the fragment and the standalone document. */
    title: string;
    overview: ManualOverview;
    functionality: ManualPage[];
    examples: ManualPage[];
    /** Prose pages, listed after the walkthroughs. */
    documents?: ManualDocument[];
    /** Outbound links for the footer. Optional, but every published manual should
     *  carry at least one. */
    links?: ManualLink[];
}
/** Where a build came from, stamped into the footer so two copies of "the
 *  manual" can be told apart without hashing them. `builtAt` defaults to now;
 *  the rest is whatever the build knows (CI knows all of it, see
 *  {@link provenanceFromEnv}). */
export interface Provenance {
    /** Source commit the captures and copy were built from. */
    sha?: string;
    /** The CI run that built it, when there was one. */
    runId?: string;
    /** ISO-8601. */
    builtAt?: string;
    /** The product version, when the build knows it. */
    version?: string;
}
/** Provenance as a GitHub Actions run sees it (GITHUB_SHA / GITHUB_RUN_ID), or
 *  as much of it as a local build has. */
export declare function provenanceFromEnv(env?: NodeJS.ProcessEnv): Provenance;
export interface BuildManualResult {
    /** Artifact-ready fragment (no doctype/head/body). */
    indexHtml: string;
    /** Complete standalone document wrapping the fragment. Always self-contained,
     *  whether or not sidecars were asked for — this is the shape that survives
     *  being published on its own. */
    standaloneHtml: string;
    /** The same document referencing the sidecar files instead of inlining them.
     *  Only present when `assets` is set, and only useful alongside `assets.dir`. */
    standaloneAssetHtml?: string;
    /** `<slug>/<file>` of every referenced capture not found on disk. */
    missing: string[];
    /** `<slug>/<file>` -> the sidecar href it was written to. Only when `assets`
     *  is set; what a bundle's markdown pages reference captures by. */
    sidecarHrefs?: Record<string, string>;
}
/** Where to write de-inlined captures for the standalone manual. `dir` is the
 *  filesystem directory; `href` (default "images") is the relative URL prefix
 *  the manual references them by — so `dir` sits at `<manual>/<href>`. */
export interface ManualAssets {
    dir: string;
    href?: string;
}
export interface BuildManualOptions {
    docsRoot: string;
    assets?: ManualAssets;
    provenance?: Provenance;
}
export declare function buildManual(spec: ManualSpec, opts: BuildManualOptions): BuildManualResult;