/**
 * Catalog for named workflows.
 *
 * Resolution order (built-ins are starting points, user workflows win):
 *   1. `~/.xopc/workflows/<name>.js` (or `<name>.workflow.js`)
 *   2. {@link BUILTIN_WORKFLOWS}
 *
 * The user dir is discovered via {@link resolveStateDir}, so `XOPC_STATE_DIR`
 * overrides apply automatically (matches how skills / extensions are wired).
 *
 * Listing is filesystem-cheap (single `readdir`) and runs synchronously — the
 * `/workflows` slash command is interactive and should return immediately.
 *
 * Validation: on load we re-parse the script to make sure `meta.name` matches
 * the filename. This prevents copy-pasted scripts from being silently
 * mis-addressed when invoked by name.
 */
import type { WorkflowMeta } from './types.js';
export type WorkflowSource = 'user' | 'builtin';
export interface CatalogEntry {
    name: string;
    source: WorkflowSource;
    /** Absolute path for user entries; null for built-ins (in-memory). */
    path: string | null;
    description: string;
    whenToUse?: string;
    tags?: string[];
    estimatedAgents?: {
        min: number;
        max: number;
    };
}
export interface LoadedWorkflow {
    name: string;
    source: WorkflowSource;
    script: string;
    meta: WorkflowMeta;
    path: string | null;
}
export interface WorkflowCatalog {
    list(): CatalogEntry[];
    /** Load a named workflow. Throws if missing or meta.name disagrees with filename. */
    load(name: string): LoadedWorkflow;
    /** Save a script as a user workflow. Throws if the script fails to parse. */
    save(name: string, script: string): {
        path: string;
    };
    /** Remove a user workflow. No-op if absent. Built-ins are never removed. */
    remove(name: string): boolean;
    /** Absolute path to the user workflows directory (created lazily on save). */
    userDir: string;
}
export declare function createWorkflowCatalog(opts?: {
    userDir?: string;
}): WorkflowCatalog;
export declare function defaultUserDir(): string;
