getseatbelt 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,1592 @@
+import { z } from 'zod';
+import { Page } from 'playwright';
+
+interface InitOptions {
+    cwd?: string;
+    /** `--yes`: accept the run + reset offers without prompting. */
+    yes?: boolean;
+    /** `--run` / `--no-run`: force running (or not) after setup, skipping the prompt. */
+    run?: boolean;
+}
+/**
+ * `seatbelt init` (alias `seatbelt on`): set up Seatbelt in this repo.
+ * Never overwrites an existing config or state file.
+ */
+declare function initCommand(opts?: InitOptions): Promise<number>;
+
+interface RunOptions {
+    cwd?: string;
+    /** `undefined`/"all" runs all flows; a flow id runs just that one (and its prerequisites). */
+    target?: string;
+    /** When false, do not auto-open the report (commander's --no-open sets open:false). */
+    open?: boolean;
+    /** Override the visible-browser default (--headed / --headless). */
+    headed?: boolean;
+    /** Accept prompts non-interactively (reserved; currently a no-op accepted flag). */
+    yes?: boolean;
+    /** "certify" records certification + freshness baselines and labels the report. */
+    mode?: "run" | "certify";
+}
+declare function runCommand(opts?: RunOptions): Promise<number>;
+
+interface CertifyOptions {
+    cwd?: string;
+    /** Run all flows as part of certification (default: don't run — just sync + show the map). */
+    run?: boolean;
+    open?: boolean;
+    headed?: boolean;
+    yes?: boolean;
+}
+/**
+ * `seatbelt certify` — the QA-certified flow-map command. Syncs the local flow map with the
+ * YAML flows, shows the map, and (with `--run`) verifies every eligible flow in a real browser
+ * and records certification + a freshness baseline. Local-first and deterministic — no AI.
+ */
+declare function certifyCommand(opts?: CertifyOptions): Promise<number>;
+
+interface RefreshFlowsOptions {
+    cwd?: string;
+    /** No backend/AI — only regenerate missing local starter templates. */
+    localOnly?: boolean;
+    ai?: boolean;
+    flow?: string;
+    apply?: boolean;
+    dryRun?: boolean;
+    provider?: "seatbelt" | "openai";
+    model?: string;
+    /** Accept safe actions non-interactively. */
+    yes?: boolean;
+}
+/**
+ * `seatbelt refresh-flows` stays local by default and uses hosted AI only with --ai.
+ *
+ * Without --ai this command:
+ *  - scaffolds the starter set if you have no flows,
+ *  - with --local-only, regenerates any MISSING starter templates (never overwrites your files),
+ *  - reports which flows look stale (dependency files changed since last certified),
+ *  - and prints the exact next steps to refresh them.
+ *
+ * With --ai it routes through the same validated suggestion path as generate-flows.
+ */
+declare function refreshFlowsCommand(opts?: RefreshFlowsOptions): Promise<number>;
+
+declare const configSchema: z.ZodDefault<z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    app: z.ZodDefault<z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        type: z.ZodOptional<z.ZodEnum<["saas", "ecommerce", "web", "api"]>>;
+        framework: z.ZodOptional<z.ZodString>;
+        packageManager: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        type?: "saas" | "ecommerce" | "web" | "api" | undefined;
+        framework?: string | undefined;
+        packageManager?: string | undefined;
+    }, {
+        type?: "saas" | "ecommerce" | "web" | "api" | undefined;
+        name?: string | undefined;
+        framework?: string | undefined;
+        packageManager?: string | undefined;
+    }>>;
+    server: z.ZodDefault<z.ZodObject<{
+        baseUrl: z.ZodDefault<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        devCommand: z.ZodOptional<z.ZodString>;
+        startTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        reuseExistingServer: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        baseUrl: string;
+        startTimeoutMs: number;
+        reuseExistingServer: boolean;
+        port?: number | undefined;
+        devCommand?: string | undefined;
+    }, {
+        baseUrl?: string | undefined;
+        port?: number | undefined;
+        devCommand?: string | undefined;
+        startTimeoutMs?: number | undefined;
+        reuseExistingServer?: boolean | undefined;
+    }>>;
+    services: z.ZodDefault<z.ZodObject<{
+        startCommand: z.ZodOptional<z.ZodString>;
+        waitFor: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        startTimeoutMs: z.ZodDefault<z.ZodNumber>;
+        reuseExisting: z.ZodDefault<z.ZodBoolean>;
+        stopOnFinish: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        startTimeoutMs: number;
+        waitFor: string[];
+        reuseExisting: boolean;
+        stopOnFinish: boolean;
+        startCommand?: string | undefined;
+    }, {
+        startTimeoutMs?: number | undefined;
+        startCommand?: string | undefined;
+        waitFor?: string[] | undefined;
+        reuseExisting?: boolean | undefined;
+        stopOnFinish?: boolean | undefined;
+    }>>;
+    checks: z.ZodDefault<z.ZodObject<{
+        lint: z.ZodOptional<z.ZodString>;
+        typecheck: z.ZodOptional<z.ZodString>;
+        build: z.ZodOptional<z.ZodString>;
+        test: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        lint?: string | undefined;
+        typecheck?: string | undefined;
+        build?: string | undefined;
+        test?: string | undefined;
+    }, {
+        lint?: string | undefined;
+        typecheck?: string | undefined;
+        build?: string | undefined;
+        test?: string | undefined;
+    }>>;
+    reset: z.ZodDefault<z.ZodObject<{
+        command: z.ZodOptional<z.ZodString>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        allowNonLocal: z.ZodDefault<z.ZodBoolean>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        verify: z.ZodOptional<z.ZodObject<{
+            expectStdoutContains: z.ZodOptional<z.ZodString>;
+            httpOk: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        }, {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        required: boolean;
+        allowNonLocal: boolean;
+        timeoutMs: number;
+        command?: string | undefined;
+        verify?: {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        } | undefined;
+    }, {
+        command?: string | undefined;
+        required?: boolean | undefined;
+        allowNonLocal?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        verify?: {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        } | undefined;
+    }>>;
+    browser: z.ZodDefault<z.ZodObject<{
+        headed: z.ZodDefault<z.ZodBoolean>;
+        freshSession: z.ZodDefault<z.ZodBoolean>;
+        slowMo: z.ZodDefault<z.ZodNumber>;
+        viewport: z.ZodDefault<z.ZodObject<{
+            width: z.ZodDefault<z.ZodNumber>;
+            height: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            height: number;
+        }, {
+            width?: number | undefined;
+            height?: number | undefined;
+        }>>;
+        video: z.ZodDefault<z.ZodBoolean>;
+        trace: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        headed: boolean;
+        freshSession: boolean;
+        slowMo: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        video: boolean;
+        trace: boolean;
+    }, {
+        headed?: boolean | undefined;
+        freshSession?: boolean | undefined;
+        slowMo?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        video?: boolean | undefined;
+        trace?: boolean | undefined;
+    }>>;
+    ai: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        backend: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        backend: string;
+    }, {
+        enabled?: boolean | undefined;
+        backend?: string | undefined;
+    }>>;
+    flows: z.ZodDefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+        run: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        autoRefresh: z.ZodDefault<z.ZodEnum<["prompt", "off", "always"]>>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+        run: string[];
+        autoRefresh: "prompt" | "off" | "always";
+    }, {
+        dir?: string | undefined;
+        run?: string[] | undefined;
+        autoRefresh?: "prompt" | "off" | "always" | undefined;
+    }>>;
+    report: z.ZodDefault<z.ZodObject<{
+        formats: z.ZodDefault<z.ZodArray<z.ZodEnum<["html", "md"]>, "many">>;
+        openOnFinish: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        formats: ("html" | "md")[];
+        openOnFinish: boolean;
+    }, {
+        formats?: ("html" | "md")[] | undefined;
+        openOnFinish?: boolean | undefined;
+    }>>;
+    env: z.ZodDefault<z.ZodObject<{
+        file: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        file: string;
+    }, {
+        file?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    app: {
+        name: string;
+        type?: "saas" | "ecommerce" | "web" | "api" | undefined;
+        framework?: string | undefined;
+        packageManager?: string | undefined;
+    };
+    server: {
+        baseUrl: string;
+        startTimeoutMs: number;
+        reuseExistingServer: boolean;
+        port?: number | undefined;
+        devCommand?: string | undefined;
+    };
+    services: {
+        startTimeoutMs: number;
+        waitFor: string[];
+        reuseExisting: boolean;
+        stopOnFinish: boolean;
+        startCommand?: string | undefined;
+    };
+    checks: {
+        lint?: string | undefined;
+        typecheck?: string | undefined;
+        build?: string | undefined;
+        test?: string | undefined;
+    };
+    reset: {
+        required: boolean;
+        allowNonLocal: boolean;
+        timeoutMs: number;
+        command?: string | undefined;
+        verify?: {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        } | undefined;
+    };
+    browser: {
+        headed: boolean;
+        freshSession: boolean;
+        slowMo: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+        video: boolean;
+        trace: boolean;
+    };
+    ai: {
+        enabled: boolean;
+        backend: string;
+    };
+    flows: {
+        dir: string;
+        run: string[];
+        autoRefresh: "prompt" | "off" | "always";
+    };
+    report: {
+        formats: ("html" | "md")[];
+        openOnFinish: boolean;
+    };
+    env: {
+        file: string;
+    };
+}, {
+    version?: number | undefined;
+    app?: {
+        type?: "saas" | "ecommerce" | "web" | "api" | undefined;
+        name?: string | undefined;
+        framework?: string | undefined;
+        packageManager?: string | undefined;
+    } | undefined;
+    server?: {
+        baseUrl?: string | undefined;
+        port?: number | undefined;
+        devCommand?: string | undefined;
+        startTimeoutMs?: number | undefined;
+        reuseExistingServer?: boolean | undefined;
+    } | undefined;
+    services?: {
+        startTimeoutMs?: number | undefined;
+        startCommand?: string | undefined;
+        waitFor?: string[] | undefined;
+        reuseExisting?: boolean | undefined;
+        stopOnFinish?: boolean | undefined;
+    } | undefined;
+    checks?: {
+        lint?: string | undefined;
+        typecheck?: string | undefined;
+        build?: string | undefined;
+        test?: string | undefined;
+    } | undefined;
+    reset?: {
+        command?: string | undefined;
+        required?: boolean | undefined;
+        allowNonLocal?: boolean | undefined;
+        timeoutMs?: number | undefined;
+        verify?: {
+            expectStdoutContains?: string | undefined;
+            httpOk?: string | undefined;
+        } | undefined;
+    } | undefined;
+    browser?: {
+        headed?: boolean | undefined;
+        freshSession?: boolean | undefined;
+        slowMo?: number | undefined;
+        viewport?: {
+            width?: number | undefined;
+            height?: number | undefined;
+        } | undefined;
+        video?: boolean | undefined;
+        trace?: boolean | undefined;
+    } | undefined;
+    ai?: {
+        enabled?: boolean | undefined;
+        backend?: string | undefined;
+    } | undefined;
+    flows?: {
+        dir?: string | undefined;
+        run?: string[] | undefined;
+        autoRefresh?: "prompt" | "off" | "always" | undefined;
+    } | undefined;
+    report?: {
+        formats?: ("html" | "md")[] | undefined;
+        openOnFinish?: boolean | undefined;
+    } | undefined;
+    env?: {
+        file?: string | undefined;
+    } | undefined;
+}>>;
+type SeatbeltConfig = z.infer<typeof configSchema>;
+
+interface ProjectPaths {
+    /** Absolute project root (cwd). */
+    cwd: string;
+    /** Absolute path to seatbelt.config.yaml. */
+    configFile: string;
+    /** Absolute path to the .seatbelt directory. */
+    seatbeltDir: string;
+    /** Absolute path to .seatbelt/state.json. */
+    stateFile: string;
+    /** Absolute path to .seatbelt/artifacts. */
+    artifactsDir: string;
+    /** Absolute path to the project .gitignore. */
+    gitignore: string;
+}
+
+interface DetectedRoute {
+    route: string;
+    file: string;
+    source: "next-app" | "next-pages" | "nuxt" | "vite-react" | "vue-router" | "generic";
+}
+declare function detectRoutes(cwd: string): DetectedRoute[];
+
+interface PrivacyDecision {
+    allowed: boolean;
+    reason: string;
+}
+interface SourceSnippet {
+    path: string;
+    content: string;
+}
+interface SourceCollection {
+    included: SourceSnippet[];
+    excluded: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+declare function privacyDecision(relPath: string, sizeBytes?: number, maxBytes?: number): PrivacyDecision;
+declare function redactSecrets(input: string): string;
+declare function collectEnvVarNames(cwd: string): string[];
+declare function collectSourceFiles(cwd: string, relPaths: string[], maxFiles?: number): SourceCollection;
+
+interface PackageSummary {
+    name: string | null;
+    scripts: Record<string, string>;
+    dependencies: string[];
+    devDependencies: string[];
+}
+interface ExistingFlowSummary {
+    id: string;
+    name: string;
+    file: string;
+    status: string | null;
+    yaml: string;
+}
+interface StaleFlowSummary {
+    id: string;
+    changedFiles: string[];
+}
+interface AppInspection {
+    cwd: string;
+    packageManager: string;
+    framework: string;
+    packageJson: PackageSummary | null;
+    routes: DetectedRoute[];
+    existingFlows: ExistingFlowSummary[];
+    stateFlowIds: string[];
+    staleFlows: StaleFlowSummary[];
+    candidateFlows: string[];
+    envVarNames: string[];
+    source: SourceCollection;
+}
+declare function inferCandidateFlows(routes: DetectedRoute[], pkg: PackageSummary | null): string[];
+declare function inspectApp(paths: ProjectPaths, config: SeatbeltConfig): Promise<AppInspection>;
+
+type FlowGenerationMode = "generate" | "refresh";
+declare function formatInspectionForPrompt(inspection: AppInspection): string;
+declare function buildFlowPrompt(inspection: AppInspection, mode: FlowGenerationMode, targetFlows?: string[]): string;
+declare function buildCopyPasteFallbackPrompt(inspection: AppInspection, targetFlows?: string[]): string;
+
+type AiProviderName = "seatbelt" | "openai";
+interface FlowAiRequest {
+    prompt: string;
+    model: string;
+    mode?: "generate-flows" | "refresh-flows";
+    cliVersion?: string;
+    project?: unknown;
+}
+interface FlowAiProvider {
+    name: AiProviderName;
+    available(): boolean;
+    generate(request: FlowAiRequest): Promise<string>;
+}
+declare function defaultModel(provider: AiProviderName): string;
+
+interface GenerateFlowsOptions {
+    cwd?: string;
+    localOnly?: boolean;
+    dryRun?: boolean;
+    yes?: boolean;
+    provider?: AiProviderName;
+    model?: string;
+}
+interface FlowGenerationRunOptions extends GenerateFlowsOptions {
+    mode: FlowGenerationMode;
+    targetFlows?: string[];
+    apply?: boolean;
+}
+declare function runFlowGeneration(opts: FlowGenerationRunOptions): Promise<number>;
+declare function generateFlowsCommand(opts?: GenerateFlowsOptions): Promise<number>;
+
+interface SetupResetOptions {
+    cwd?: string;
+}
+/**
+ * `seatbelt setup-reset` / `seatbelt reset-prompt` — generate (never execute) a paste-ready
+ * prompt that asks the user's coding agent to add a safe clean-test-user reset script.
+ */
+declare function setupResetCommand(opts?: SetupResetOptions): Promise<number>;
+
+interface LintOptions {
+    cwd?: string;
+}
+/**
+ * `seatbelt lint` — a fast, non-browser safety pass. Runs the detected lint / typecheck /
+ * build / test scripts sequentially. Free and local; never touches a backend.
+ */
+declare function lintCommand(opts?: LintOptions): Promise<number>;
+
+interface DoctorOptions {
+    cwd?: string;
+}
+/**
+ * `seatbelt doctor` — plain-language diagnosis of the project. Never a stack trace,
+ * never requires a backend. Exit 0 if the project looks runnable, 1 if there's a blocker.
+ */
+declare function doctorCommand(opts?: DoctorOptions): Promise<number>;
+
+interface ReportOptions {
+    cwd?: string;
+    /** Print the path instead of opening the report. */
+    path?: boolean;
+}
+/**
+ * `seatbelt report` — open the latest report without re-running QA.
+ */
+declare function reportCommand(opts?: ReportOptions): Promise<number>;
+
+interface LoadOptions {
+    cwd?: string;
+    /** CLI flags that override the config file (highest precedence). */
+    overrides?: Record<string, unknown>;
+}
+interface LoadedConfig {
+    config: SeatbeltConfig;
+    configFileExists: boolean;
+    paths: ProjectPaths;
+}
+/**
+ * Load and validate config. Merge order (highest wins):
+ *   defaults  <  detected  <  seatbelt.config.yaml  <  CLI overrides
+ *
+ * Validation errors are returned in plain language — raw zod output is only shown
+ * when SEATBELT_DEBUG=1 (via the top-level error printer).
+ */
+declare function loadConfig(opts?: LoadOptions): Promise<LoadedConfig>;
+
+/** The fully-defaulted config (what you get with an empty file). */
+declare function defaultConfig(): SeatbeltConfig;
+/**
+ * The minimal starter config `seatbelt on` writes. Deliberately tiny — the point
+ * is near-zero config. Everything omitted here falls back to schema defaults.
+ */
+declare const STARTER_CONFIG_YAML = "version: 1\napp:\n  name: My app\n\nserver:\n  baseUrl: http://localhost:3000\n  reuseExistingServer: true\n\nbrowser:\n  headed: true\n  freshSession: true\n  video: true\n  trace: false\n\nreport:\n  formats:\n    - html\n  openOnFinish: true\n\nflows:\n  dir: qa-flows\n  autoRefresh: prompt\n\n# Clean test user (optional but recommended). Run `seatbelt setup-reset` to generate\n# a prompt that adds a safe reset script to your app, then uncomment and set required: true.\n# reset:\n#   command: npm run qa:reset-user\n#   required: true\n#   timeoutMs: 30000\n#   allowNonLocal: false\n";
+
+/**
+ * Conservative project detection. Suggests defaults for framework / package manager /
+ * scripts / baseUrl. The config file always overrides these (see config/load.ts precedence).
+ */
+type DetectedFramework = "nextjs" | "nuxt" | "quasar" | "vite" | "node";
+type DetectedPackageManager = "pnpm" | "yarn" | "npm";
+interface DetectedConfig {
+    app?: {
+        framework?: string;
+        packageManager?: string;
+    };
+    server?: {
+        devCommand?: string;
+        baseUrl?: string;
+        port?: number;
+    };
+    checks?: {
+        build?: string;
+        lint?: string;
+        typecheck?: string;
+        test?: string;
+    };
+}
+interface DetectionSummary extends DetectedConfig {
+    framework: DetectedFramework;
+    packageManager: DetectedPackageManager;
+    livePortFound: boolean;
+    hasPackageJson: boolean;
+    /** All package.json script names (for `seatbelt doctor`). */
+    scripts: string[];
+    /** Detected Docker Compose file name, if any (we do NOT orchestrate it — just report it). */
+    composeFile: string | null;
+    /** Names (never values) of .env* files present. */
+    envFiles: string[];
+}
+declare function detect(paths: ProjectPaths): Promise<DetectionSummary>;
+/** The plain object merged into config (only the config-shaped subset). */
+declare function detectConfig(paths: ProjectPaths): Promise<DetectedConfig>;
+
+interface ServerHandle {
+    /** True only if Seatbelt itself started this dev server (and is therefore allowed to stop it). */
+    startedBySeatbelt: boolean;
+    ready: boolean;
+    /** Absolute path to the captured server log, if Seatbelt started the server. */
+    logPath: string | null;
+    /** Friendly message when `ready` is false. */
+    error?: string;
+    stop(): Promise<void>;
+}
+/**
+ * Ensure the app is serving at `config.server.baseUrl` before browser QA.
+ * - Reuse it if already reachable.
+ * - Otherwise auto-start the detected/configured dev command, but only for a localhost URL.
+ * - Stream logs to `<runDir>/server.log`. Wait up to `server.startTimeoutMs`.
+ * - Never stop a server it did not start.
+ */
+declare function ensureServer(config: SeatbeltConfig, cwd: string, runDir: string): Promise<ServerHandle>;
+
+/**
+ * The "clean test user" reset. Seatbelt runs the user's own project-specific reset command
+ * before browser flows so every run starts from a known state. It is NOT universal magic —
+ * the command is written by the user's coding agent (see `seatbelt setup-reset`).
+ */
+type ResetStatus = "passed" | "failed" | "skipped" | "missing" | "refused" | "not-run";
+interface ResetReport {
+    configured: boolean;
+    required: boolean;
+    command: string | null;
+    status: ResetStatus;
+    exitCode: number | null;
+    durationMs: number;
+    logFile: string | null;
+    /** HTTP health verification (verify.httpOk), when configured. */
+    verifyHttpUrl: string | null;
+    verifyHttpOk: boolean | null;
+    summary: string;
+}
+/** A reset problem that must stop browser QA (verdict DO NOT MERGE). */
+declare function resetBlocksRun(r: ResetReport): boolean;
+/** A reset problem that is only a caution (results may be contaminated), but doesn't block. */
+declare function resetIsCaution(r: ResetReport): boolean;
+/** Resolve a verify.httpOk value (absolute URL, or a path against baseUrl) to an absolute URL. */
+declare function resolveVerifyUrl(httpOk: string, baseUrl: string): string;
+/** A reset report used when reset wasn't attempted (e.g. app unreachable). */
+declare function resetNotRun(config: SeatbeltConfig, reason: string): ResetReport;
+declare function runReset(config: SeatbeltConfig, cwd: string, runDir: string, baseUrl: string): Promise<ResetReport>;
+
+/**
+ * Generates the paste-ready "make a clean test user" prompt for the user's coding agent,
+ * plus the config snippet to wire it up. Framing stays plain-language (no "hook"/"fixture").
+ */
+interface ResetPromptContext {
+    framework?: string | null;
+    packageManager?: string | null;
+}
+/** The command the user will end up with, respecting their package manager. */
+declare function resetRunCommand(context: ResetPromptContext): string;
+/** The suggested seatbelt.config.yaml snippet. */
+declare function resetConfigSnippet(context: ResetPromptContext): string;
+/** The full paste-ready agent prompt. Generic across Next.js / Vite / Quasar / other web apps. */
+declare function buildResetPrompt(context: ResetPromptContext): string;
+
+declare const flowStepSchema: z.ZodUnion<[z.ZodObject<{
+    goto: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    goto: string;
+}, {
+    goto: string;
+}>, z.ZodObject<{
+    click: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    click: string;
+}, {
+    click: string;
+}>, z.ZodObject<{
+    fill: z.ZodEffects<z.ZodObject<{
+        selector: z.ZodString;
+        value: z.ZodOptional<z.ZodString>;
+        valueFromEnv: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    }, {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    }>, {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    }, {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    fill: {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    };
+}, {
+    fill: {
+        selector: string;
+        value?: string | undefined;
+        valueFromEnv?: string | undefined;
+    };
+}>, z.ZodObject<{
+    press: z.ZodUnion<[z.ZodString, z.ZodObject<{
+        key: z.ZodString;
+        selector: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        key: string;
+        selector?: string | undefined;
+    }, {
+        key: string;
+        selector?: string | undefined;
+    }>]>;
+}, "strict", z.ZodTypeAny, {
+    press: string | {
+        key: string;
+        selector?: string | undefined;
+    };
+}, {
+    press: string | {
+        key: string;
+        selector?: string | undefined;
+    };
+}>, z.ZodObject<{
+    selectOption: z.ZodObject<{
+        selector: z.ZodString;
+        value: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        value: string;
+        selector: string;
+    }, {
+        value: string;
+        selector: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    selectOption: {
+        value: string;
+        selector: string;
+    };
+}, {
+    selectOption: {
+        value: string;
+        selector: string;
+    };
+}>, z.ZodObject<{
+    upload: z.ZodObject<{
+        selector: z.ZodString;
+        path: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        selector: string;
+    }, {
+        path: string;
+        selector: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    upload: {
+        path: string;
+        selector: string;
+    };
+}, {
+    upload: {
+        path: string;
+        selector: string;
+    };
+}>, z.ZodObject<{
+    waitForUrlContains: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    waitForUrlContains: string;
+}, {
+    waitForUrlContains: string;
+}>, z.ZodObject<{
+    waitForText: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    waitForText: string;
+}, {
+    waitForText: string;
+}>, z.ZodObject<{
+    waitForTimeoutMs: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    waitForTimeoutMs: number;
+}, {
+    waitForTimeoutMs: number;
+}>, z.ZodObject<{
+    expectUrlContains: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expectUrlContains: string;
+}, {
+    expectUrlContains: string;
+}>, z.ZodObject<{
+    expectText: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expectText: string;
+}, {
+    expectText: string;
+}>, z.ZodObject<{
+    expectVisible: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expectVisible: string;
+}, {
+    expectVisible: string;
+}>, z.ZodObject<{
+    expectNotVisible: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expectNotVisible: string;
+}, {
+    expectNotVisible: string;
+}>, z.ZodObject<{
+    expectTitleContains: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    expectTitleContains: string;
+}, {
+    expectTitleContains: string;
+}>, z.ZodObject<{
+    screenshot: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    screenshot: string;
+}, {
+    screenshot: string;
+}>]>;
+declare const flowDependenciesSchema: z.ZodDefault<z.ZodObject<{
+    files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    routes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    services: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    services: string[];
+    files: string[];
+    routes: string[];
+}, {
+    services?: string[] | undefined;
+    files?: string[] | undefined;
+    routes?: string[] | undefined;
+}>>;
+declare const flowSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodDefault<z.ZodString>;
+    critical: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Declared status. Optional. `yellow` means "template — needs setup" and is skipped in
+     * bulk `seatbelt run` / `seatbelt certify --run` (still shown in the map). Run it explicitly
+     * (`seatbelt run <id>`) or remove the line once it's configured to include it in bulk runs.
+     */
+    status: z.ZodOptional<z.ZodEnum<["grey", "green", "yellow", "red", "blocked"]>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    dependencies: z.ZodDefault<z.ZodObject<{
+        files: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        routes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        services: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        services: string[];
+        files: string[];
+        routes: string[];
+    }, {
+        services?: string[] | undefined;
+        files?: string[] | undefined;
+        routes?: string[] | undefined;
+    }>>;
+    requires: z.ZodDefault<z.ZodObject<{
+        env: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        env: string[];
+    }, {
+        env?: string[] | undefined;
+    }>>;
+    /**
+     * Prerequisite flow ids that must pass first (e.g. a dashboard flow `needs: [login]`).
+     * Prereqs run before the dependent, once per run, and share its browser context so login
+     * carries into the dependent. A failed prereq blocks the dependent.
+     */
+    needs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    startUrl: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodUnion<[z.ZodObject<{
+        goto: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        goto: string;
+    }, {
+        goto: string;
+    }>, z.ZodObject<{
+        click: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        click: string;
+    }, {
+        click: string;
+    }>, z.ZodObject<{
+        fill: z.ZodEffects<z.ZodObject<{
+            selector: z.ZodString;
+            value: z.ZodOptional<z.ZodString>;
+            valueFromEnv: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        }, {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        }>, {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        }, {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        fill: {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        };
+    }, {
+        fill: {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        };
+    }>, z.ZodObject<{
+        press: z.ZodUnion<[z.ZodString, z.ZodObject<{
+            key: z.ZodString;
+            selector: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            key: string;
+            selector?: string | undefined;
+        }, {
+            key: string;
+            selector?: string | undefined;
+        }>]>;
+    }, "strict", z.ZodTypeAny, {
+        press: string | {
+            key: string;
+            selector?: string | undefined;
+        };
+    }, {
+        press: string | {
+            key: string;
+            selector?: string | undefined;
+        };
+    }>, z.ZodObject<{
+        selectOption: z.ZodObject<{
+            selector: z.ZodString;
+            value: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            value: string;
+            selector: string;
+        }, {
+            value: string;
+            selector: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        selectOption: {
+            value: string;
+            selector: string;
+        };
+    }, {
+        selectOption: {
+            value: string;
+            selector: string;
+        };
+    }>, z.ZodObject<{
+        upload: z.ZodObject<{
+            selector: z.ZodString;
+            path: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            path: string;
+            selector: string;
+        }, {
+            path: string;
+            selector: string;
+        }>;
+    }, "strict", z.ZodTypeAny, {
+        upload: {
+            path: string;
+            selector: string;
+        };
+    }, {
+        upload: {
+            path: string;
+            selector: string;
+        };
+    }>, z.ZodObject<{
+        waitForUrlContains: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        waitForUrlContains: string;
+    }, {
+        waitForUrlContains: string;
+    }>, z.ZodObject<{
+        waitForText: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        waitForText: string;
+    }, {
+        waitForText: string;
+    }>, z.ZodObject<{
+        waitForTimeoutMs: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        waitForTimeoutMs: number;
+    }, {
+        waitForTimeoutMs: number;
+    }>, z.ZodObject<{
+        expectUrlContains: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expectUrlContains: string;
+    }, {
+        expectUrlContains: string;
+    }>, z.ZodObject<{
+        expectText: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expectText: string;
+    }, {
+        expectText: string;
+    }>, z.ZodObject<{
+        expectVisible: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expectVisible: string;
+    }, {
+        expectVisible: string;
+    }>, z.ZodObject<{
+        expectNotVisible: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expectNotVisible: string;
+    }, {
+        expectNotVisible: string;
+    }>, z.ZodObject<{
+        expectTitleContains: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        expectTitleContains: string;
+    }, {
+        expectTitleContains: string;
+    }>, z.ZodObject<{
+        screenshot: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        screenshot: string;
+    }, {
+        screenshot: string;
+    }>]>, "many">;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    description: string;
+    critical: boolean;
+    tags: string[];
+    dependencies: {
+        services: string[];
+        files: string[];
+        routes: string[];
+    };
+    requires: {
+        env: string[];
+    };
+    needs: string[];
+    steps: ({
+        goto: string;
+    } | {
+        click: string;
+    } | {
+        fill: {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        };
+    } | {
+        press: string | {
+            key: string;
+            selector?: string | undefined;
+        };
+    } | {
+        selectOption: {
+            value: string;
+            selector: string;
+        };
+    } | {
+        upload: {
+            path: string;
+            selector: string;
+        };
+    } | {
+        waitForUrlContains: string;
+    } | {
+        waitForText: string;
+    } | {
+        waitForTimeoutMs: number;
+    } | {
+        expectUrlContains: string;
+    } | {
+        expectText: string;
+    } | {
+        expectVisible: string;
+    } | {
+        expectNotVisible: string;
+    } | {
+        expectTitleContains: string;
+    } | {
+        screenshot: string;
+    })[];
+    status?: "grey" | "green" | "yellow" | "red" | "blocked" | undefined;
+    startUrl?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    steps: ({
+        goto: string;
+    } | {
+        click: string;
+    } | {
+        fill: {
+            selector: string;
+            value?: string | undefined;
+            valueFromEnv?: string | undefined;
+        };
+    } | {
+        press: string | {
+            key: string;
+            selector?: string | undefined;
+        };
+    } | {
+        selectOption: {
+            value: string;
+            selector: string;
+        };
+    } | {
+        upload: {
+            path: string;
+            selector: string;
+        };
+    } | {
+        waitForUrlContains: string;
+    } | {
+        waitForText: string;
+    } | {
+        waitForTimeoutMs: number;
+    } | {
+        expectUrlContains: string;
+    } | {
+        expectText: string;
+    } | {
+        expectVisible: string;
+    } | {
+        expectNotVisible: string;
+    } | {
+        expectTitleContains: string;
+    } | {
+        screenshot: string;
+    })[];
+    status?: "grey" | "green" | "yellow" | "red" | "blocked" | undefined;
+    description?: string | undefined;
+    critical?: boolean | undefined;
+    tags?: string[] | undefined;
+    dependencies?: {
+        services?: string[] | undefined;
+        files?: string[] | undefined;
+        routes?: string[] | undefined;
+    } | undefined;
+    requires?: {
+        env?: string[] | undefined;
+    } | undefined;
+    needs?: string[] | undefined;
+    startUrl?: string | undefined;
+}>;
+type Flow = z.infer<typeof flowSchema>;
+type FlowStep = z.infer<typeof flowStepSchema>;
+type FlowDependencies$1 = z.infer<typeof flowDependenciesSchema>;
+/** True when a flow is a template that still needs setup (declared `status: yellow`). */
+declare function isNeedsSetup(flow: Flow): boolean;
+
+declare const STARTER_FLOW_ID = "homepage-smoke";
+interface FlowLoadError {
+    file: string;
+    message: string;
+}
+interface LoadFlowsResult {
+    flowsDir: string;
+    flows: Flow[];
+    createdStarter: boolean;
+    /** ids of any starter templates created because the dir was empty. */
+    createdFlowIds: string[];
+    errors: FlowLoadError[];
+}
+/**
+ * Ensure the flows dir exists and, when empty, scaffold the starter flow set.
+ * Returns the ids of any created templates (empty if flows already existed).
+ */
+declare function ensureFlowsDir(flowsDir: string): Promise<string[]>;
+interface LoadFlowsOptions {
+    /** Create a starter flow when the directory is empty (default true). Set false for read-only inspection. */
+    create?: boolean;
+}
+/**
+ * Load and validate all flows in `<cwd>/<flowsDirName>`. By default creates a starter flow if
+ * the directory is empty. Invalid flows are skipped and reported (never crash the run).
+ */
+declare function loadFlows(cwd: string, flowsDirName: string, options?: LoadFlowsOptions): Promise<LoadFlowsResult>;
+
+/**
+ * Starter flow templates. Written when `qa-flows/` has no flows yet (by `seatbelt on`,
+ * `seatbelt run`, or `seatbelt certify`).
+ *
+ * Design rules (kept generic on purpose — validated against Syllawise's Next.js + Quasar
+ * apps, but NOT overfit to them):
+ *  - Homepage runs immediately (no setup).
+ *  - login / dashboard / signup / upload / checkout ship as `status: yellow` = "needs setup":
+ *    they appear in the QA map but are SKIPPED in bulk runs until you configure them and
+ *    remove the `status: yellow` line (or run them explicitly with `seatbelt run <id>`).
+ *  - Selectors prefer stable attributes (type / placeholder / role / text) over brittle ones,
+ *    and every template says, in a comment, to confirm routes + selectors for YOUR app.
+ */
+interface FlowTemplate {
+    id: string;
+    yaml: string;
+}
+/** The full starter set, in a sensible display order. */
+declare const STARTER_FLOW_TEMPLATES: FlowTemplate[];
+/**
+ * Ensure the flows dir exists and, if it has NO flow files yet, write the full starter set.
+ * Never adds files to an existing set (so we don't surprise users who already have flows).
+ * Returns the ids of any templates created (empty if flows already existed).
+ */
+declare function ensureStarterFlows(flowsDir: string): Promise<string[]>;
+
+/** Whether the configured env file exists (for a friendly "add your creds" warning). */
+declare function envFileExists(cwd: string, envFile: string): boolean;
+/**
+ * Resolve env values from the project env file, with `process.env` taking precedence
+ * (so CI / shell overrides win, matching dotenv's default of not clobbering existing vars).
+ */
+declare function loadEnvValues(cwd: string, envFile: string): Record<string, string>;
+/** All env var names a flow needs: `requires.env` plus any referenced by `valueFromEnv`. */
+declare function requiredEnvForFlow(flow: Flow): string[];
+/** Which required env vars are missing/empty in the resolved values. */
+declare function missingEnvForFlow(flow: Flow, values: Record<string, string>): string[];
+
+/**
+ * Flow prerequisite graph (`needs`). Deterministic, small, no magic:
+ *  - validate that every `needs` id exists,
+ *  - detect cycles (with a friendly loop path),
+ *  - expand a set of "root" flows to the closure of their prerequisites,
+ *  - group flows into "journeys" (weakly-connected components) so a prereq like login runs once
+ *    and its browser context (auth) carries into every dependent, while unrelated flows stay
+ *    in fresh, isolated contexts.
+ */
+interface GraphError {
+    message: string;
+}
+/** Report any `needs` that reference a non-existent flow id. */
+declare function validateNeeds(flows: Flow[]): GraphError[];
+/**
+ * Find one dependency cycle, if any, and return its path (e.g. ["login","dash","login"]).
+ * Returns null when the graph is acyclic. Missing `needs` ids are ignored here (validateNeeds
+ * reports those separately).
+ */
+declare function findCycle(flows: Flow[]): string[] | null;
+/**
+ * Expand `roots` to include all transitive prerequisites. Order is not guaranteed here
+ * (use `topoSort` for ordering). Unknown ids are skipped.
+ */
+declare function expandWithPrereqs(rootIds: string[], byId: Map<string, Flow>): Set<string>;
+/** Topologically sort a subset of flow ids so every prerequisite comes before its dependents. */
+declare function topoSort(ids: Set<string>, byId: Map<string, Flow>): string[];
+/**
+ * Group a set of flow ids into journeys: weakly-connected components over `needs` edges.
+ * Flows linked by prerequisites end up in the same journey (one shared browser context);
+ * independent flows are their own singleton journeys (fresh context each).
+ * Each returned journey is topologically ordered (prereqs first).
+ */
+declare function journeys(ids: Set<string>, byId: Map<string, Flow>): string[][];
+
+interface FlowMetaEntry {
+    dependencies: FlowDependencies$1;
+    /** path -> sha1 of file contents, captured at the last certification. */
+    fingerprint: Record<string, string>;
+    lastCertifiedRunId: string | null;
+    lastCertifiedAt: string | null;
+}
+interface FlowMeta {
+    version: number;
+    flows: Record<string, FlowMetaEntry>;
+}
+interface StaleResult {
+    stale: boolean;
+    changedFiles: string[];
+}
+declare function readFlowMeta(paths: ProjectPaths): FlowMeta;
+declare function writeFlowMeta(paths: ProjectPaths, meta: FlowMeta): Promise<void>;
+/**
+ * Fingerprint a flow's declared dependency files (literal paths only). Missing files and
+ * glob patterns are skipped in the Day-4 seed — the fingerprint is a best-effort signal.
+ */
+declare function fingerprintDependencies(cwd: string, deps: FlowDependencies$1): Record<string, string>;
+/** Compare a current fingerprint against a stored baseline. Stale only if a baseline existed. */
+declare function detectStale(current: Record<string, string>, baseline: Record<string, string> | undefined): StaleResult;
+
+interface StepResult {
+    index: number;
+    label: string;
+    ok: boolean;
+    error: string | null;
+}
+interface FlowRunResult {
+    id: string;
+    name: string;
+    description: string;
+    critical: boolean;
+    status: "green" | "red";
+    finalUrl: string | null;
+    pageTitle: string | null;
+    steps: StepResult[];
+    /** Absolute paths of screenshots captured during the flow. */
+    screenshots: string[];
+    consoleErrors: string[];
+    networkFailures: string[];
+    failureSummary: string | null;
+    durationMs: number;
+}
+/**
+ * Run one flow on a fresh page. Attaches console/network listeners, executes steps in
+ * order, stops on the first failing step (capturing a last-state screenshot), and never
+ * throws — failures are returned in the result so the caller can continue to the next flow.
+ */
+declare function runFlow(page: Page, flow: Flow, baseUrl: string, runDir: string, env: Record<string, string>, cwd: string): Promise<FlowRunResult>;
+
+interface ParsedFlowYaml {
+    id: string;
+    yaml: string;
+    flow: Flow;
+}
+interface RejectedFlowYaml {
+    yaml: string;
+    error: string;
+}
+interface ExtractedYamlResult {
+    valid: ParsedFlowYaml[];
+    rejected: RejectedFlowYaml[];
+}
+declare function extractFlowYaml(text: string): ExtractedYamlResult;
+
+interface FlowSuggestion {
+    id: string;
+    yaml: string;
+    flow: Flow;
+    source: "local" | "ai";
+    assumptions: string[];
+    rejected?: RejectedFlowYaml[];
+}
+declare function localFlowSuggestions(inspection: AppInspection, requestedIds?: string[]): FlowSuggestion[];
+declare function aiFlowSuggestions(output: string): {
+    suggestions: FlowSuggestion[];
+    rejected: RejectedFlowYaml[];
+};
+
+declare class OpenAIFlowProvider implements FlowAiProvider {
+    private readonly apiKey;
+    readonly name: "openai";
+    constructor(apiKey?: string | undefined);
+    available(): boolean;
+    generate(request: FlowAiRequest): Promise<string>;
+}
+
+declare function seatbeltApiUrl(): string;
+/**
+ * Resolve the Seatbelt token. Precedence: SEATBELT_API_TOKEN / SEATBELT_API_KEY env
+ * (advanced / CI override) → the token stored by `seatbelt login` → none. This lets
+ * the normal flow "just work" after a one-time browser login, with the env var kept
+ * as an advanced/CI fallback.
+ */
+declare function seatbeltApiToken(): string | undefined;
+declare function hostedAiDisabled(): boolean;
+declare class SeatbeltFlowProvider implements FlowAiProvider {
+    readonly name: "seatbelt";
+    private readonly apiUrl;
+    private readonly token?;
+    constructor(apiUrl?: string, token?: string | undefined);
+    available(): boolean;
+    destination(): string;
+    generate(request: FlowAiRequest): Promise<string>;
+}
+
+/**
+ * Local Seatbelt state — the "QA-certified flow map". It tracks every discovered flow, its
+ * status, the files/routes/services it depends on, the env it requires, and when it was last
+ * certified (verified by an actual run). This is the durable value that grows over time.
+ */
+/**
+ * Flow status state machine:
+ *   grey    = discovered but not tested yet
+ *   green   = tested and passed
+ *   yellow  = needs setup / stale / partially verified (e.g. a template not yet configured)
+ *   red     = tested and failed
+ *   blocked = could not run because setup/config is missing (server down, env missing)
+ */
+type FlowStatus = "grey" | "green" | "yellow" | "red" | "blocked";
+interface FlowDependencies {
+    files: string[];
+    routes: string[];
+    services: string[];
+}
+interface FlowRequires {
+    env: string[];
+}
+interface FlowCertification {
+    lastCertifiedAt: string | null;
+    lastCertifiedRunId: string | null;
+}
+interface FlowState {
+    id: string;
+    name: string;
+    status: FlowStatus;
+    description: string;
+    tags: string[];
+    lastRunId: string | null;
+    lastRunAt: string | null;
+    lastReportPath: string | null;
+    lastFailureSummary: string | null;
+    dependencies: FlowDependencies;
+    requires: FlowRequires;
+    needs: string[];
+    certification: FlowCertification;
+}
+interface SeatbeltState {
+    version: number;
+    project: {
+        name: string;
+    };
+    flows: FlowState[];
+}
+declare const HOMEPAGE_SMOKE_ID = "homepage-smoke";
+declare function emptyDependencies(): FlowDependencies;
+declare function emptyCertification(): FlowCertification;
+/** The initial state written by `seatbelt on`. */
+declare function seedState(projectName: string): SeatbeltState;
+declare function loadState(stateFile: string): Promise<SeatbeltState | null>;
+declare function saveState(stateFile: string, state: SeatbeltState): Promise<void>;
+/**
+ * Load state, or seed a fresh one if it doesn't exist yet (e.g. the user ran
+ * `seatbelt run` before `seatbelt on`). Keeps `run` resilient.
+ */
+declare function loadOrSeedState(stateFile: string, projectName: string): Promise<SeatbeltState>;
+/**
+ * Update (or insert) a flow by id, returning a new state. Existing status/history is
+ * preserved for fields not provided.
+ */
+declare function upsertFlow(state: SeatbeltState, patch: Pick<FlowState, "id" | "name"> & Partial<FlowState>): SeatbeltState;
+/** The metadata Seatbelt syncs from a flow's YAML into the map (never touches run history). */
+interface FlowSyncInput {
+    id: string;
+    name: string;
+    description: string;
+    tags: string[];
+    dependencies: FlowDependencies;
+    requires: FlowRequires;
+    needs: string[];
+    /** Declared status from YAML, used only to seed a brand-new flow entry. */
+    declaredStatus?: FlowStatus;
+}
+/**
+ * Sync flow metadata (name/description/tags/dependencies/requires) from YAML into the map.
+ * - Existing flows keep their status + run history + certification; only metadata is refreshed.
+ * - New flows are created with their declared status (or grey).
+ */
+declare function syncFlowsFromYaml(state: SeatbeltState, inputs: FlowSyncInput[]): SeatbeltState;
+/** Record that a flow was certified (verified by a certify run). */
+declare function recordCertification(state: SeatbeltState, id: string, runId: string, at: string): SeatbeltState;
+
+/**
+ * Tri-state merge verdict (Day 4). One glance = one decision.
+ *
+ *   merge          ✅  required reset ok/skipped, all selected critical flows passed, no noise
+ *   caution        ⚠   non-critical trouble, needs-setup flows, stale flows, or passing-with-errors
+ *   do_not_merge   ⛔  required reset failed/missing, or a critical flow failed / couldn't run
+ *
+ * Exit code: merge/caution -> 0, do_not_merge -> 1 (per REPORT_SPEC).
+ */
+type Verdict = "merge" | "caution" | "do_not_merge";
+interface VerdictResult {
+    verdict: Verdict;
+    reasons: string[];
+}
+/** Just the shape the verdict needs from each flow (a subset of FlowReport). */
+interface FlowVerdictInput {
+    id: string;
+    critical: boolean;
+    status: FlowStatus;
+    stale: boolean;
+    missingEnv: string[];
+    blockedByPrereq: string | null;
+    consoleErrors: string[];
+    networkFailures: string[];
+}
+interface VerdictContext {
+    /** The app/dev server could not be reached — nothing could run. */
+    serverUnavailable?: boolean;
+}
+declare function verdictLabel(v: Verdict): string;
+declare function verdictEmoji(v: Verdict): string;
+declare function verdictExitCode(v: Verdict): number;
+/** CSS class used in the HTML banner/pill. */
+declare function verdictClass(v: Verdict): string;
+declare function computeVerdict(flows: FlowVerdictInput[], reset: ResetReport, context?: VerdictContext): VerdictResult;
+
+/** A single step's outcome, for the report. */
+interface StepReportItem {
+    index: number;
+    label: string;
+    ok: boolean;
+    error: string | null;
+}
+interface ScreenshotItem {
+    name: string;
+    dataUri: string;
+}
+interface FlowReport {
+    id: string;
+    name: string;
+    description: string;
+    critical: boolean;
+    status: FlowStatus;
+    tags: string[];
+    dependencies: FlowDependencies;
+    requiresEnv: string[];
+    missingEnv: string[];
+    needsSetup: boolean;
+    needs: string[];
+    blockedByPrereq: string | null;
+    stale: boolean;
+    staleFiles: string[];
+    finalUrl: string | null;
+    pageTitle: string | null;
+    failureSummary: string | null;
+    /** A plain-language note for flows that were not executed (needs setup / blocked). */
+    note: string | null;
+    durationMs: number;
+    steps: StepReportItem[];
+    screenshots: ScreenshotItem[];
+    videoFile: string | null;
+    traceFile: string | null;
+    consoleErrors: string[];
+    networkFailures: string[];
+}
+interface RunReport {
+    runId: string;
+    generatedAt: string;
+    mode: "run" | "certify";
+    verdict: Verdict;
+    verdictReasons: string[];
+    baseUrl: string;
+    framework: string | null;
+    packageManager: string | null;
+    serverStartedBySeatbelt: boolean;
+    serverLogFile: string | null;
+    artifactDir: string;
+    sessionFresh: boolean;
+    seatbeltVersion: string;
+    reset: ResetReport;
+    flows: FlowReport[];
+}
+interface StatusCounts {
+    green: number;
+    yellow: number;
+    red: number;
+    blocked: number;
+    grey: number;
+}
+declare function countStatuses(flows: FlowReport[]): StatusCounts;
+/**
+ * Deterministic, paste-ready fix prompt for Claude / Cursor / Codex. Never depends on AI —
+ * this is the local fallback that always works.
+ */
+declare function buildFixPrompt(report: RunReport): string;
+declare function renderReportHtml(r: RunReport): string;
+/** Compact markdown report, written only when `report.formats` includes "md". */
+declare function renderReportMarkdown(r: RunReport): string;
+
+declare function isLocalhostUrl(url: string): boolean;
+/** TCP connect check — resolves true if something is listening on host:port. */
+declare function probePort(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+declare function isUrlReachable(url: string, timeoutMs?: number): Promise<boolean>;
+/** Probe ports in parallel; return the first (in list order) that is reachable. */
+declare function firstReachablePort(host: string, ports: number[], timeoutMs?: number): Promise<number | null>;
+/** Poll until the URL is reachable or the timeout elapses. */
+declare function waitForUrlReachable(url: string, timeoutMs: number, intervalMs?: number): Promise<boolean>;
+
+declare const VERSION = "0.0.1";
+
+export { type AiProviderName, type AppInspection, type CertifyOptions, type DetectedConfig, type DetectedFramework, type DetectedPackageManager, type DetectedRoute, type DetectionSummary, type DoctorOptions, type ExtractedYamlResult, type Flow, type FlowAiProvider, type FlowAiRequest, type FlowCertification, type FlowDependencies, type FlowGenerationRunOptions, type FlowLoadError, type FlowMeta, type FlowMetaEntry, type FlowReport, type FlowRequires, type FlowRunResult, type FlowState, type FlowStatus, type FlowStep, type FlowSuggestion, type FlowSyncInput, type FlowTemplate, type FlowVerdictInput, type GenerateFlowsOptions, type GraphError, HOMEPAGE_SMOKE_ID, type InitOptions, type LintOptions, type LoadFlowsResult, type LoadOptions, type LoadedConfig, OpenAIFlowProvider, type ParsedFlowYaml, type PrivacyDecision, type RefreshFlowsOptions, type RejectedFlowYaml, type ReportOptions, type ResetReport, type ResetStatus, type RunOptions, type RunReport, STARTER_CONFIG_YAML, STARTER_FLOW_ID, STARTER_FLOW_TEMPLATES, type SeatbeltConfig, SeatbeltFlowProvider, type SeatbeltState, type ServerHandle, type SetupResetOptions, type SourceCollection, type SourceSnippet, type StaleResult, type StatusCounts, type StepReportItem, type StepResult, VERSION, type Verdict, type VerdictContext, type VerdictResult, aiFlowSuggestions, buildCopyPasteFallbackPrompt, buildFixPrompt, buildFlowPrompt, buildResetPrompt, certifyCommand, collectEnvVarNames, collectSourceFiles, computeVerdict, configSchema, countStatuses, defaultConfig, defaultModel, detect, detectConfig, detectRoutes, detectStale, doctorCommand, emptyCertification, emptyDependencies, ensureFlowsDir, ensureServer, ensureStarterFlows, envFileExists, expandWithPrereqs, extractFlowYaml, findCycle, fingerprintDependencies, firstReachablePort, flowSchema, flowStepSchema, formatInspectionForPrompt, generateFlowsCommand, hostedAiDisabled, inferCandidateFlows, initCommand, inspectApp, isLocalhostUrl, isNeedsSetup, isUrlReachable, journeys, lintCommand, loadConfig, loadEnvValues, loadFlows, loadOrSeedState, loadState, localFlowSuggestions, missingEnvForFlow, privacyDecision, probePort, readFlowMeta, recordCertification, redactSecrets, refreshFlowsCommand, renderReportHtml, renderReportMarkdown, reportCommand, requiredEnvForFlow, resetBlocksRun, resetConfigSnippet, resetIsCaution, resetNotRun, resetRunCommand, resolveVerifyUrl, runCommand, runFlow, runFlowGeneration, runReset, saveState, seatbeltApiToken, seatbeltApiUrl, seedState, setupResetCommand, syncFlowsFromYaml, topoSort, upsertFlow, validateNeeds, verdictClass, verdictEmoji, verdictExitCode, verdictLabel, waitForUrlReachable, writeFlowMeta };