export declare const REFERENCE_DIR: string;
export declare function referenceDirPath(root: string): string;
export declare function acceptedReferencePath(root: string): string;
export declare function candidateImagePath(root: string, id: string): string;
/** One generated candidate — a picture the creator may accept, iterate from, or ignore. */
export interface CandidateRecord {
    id: string;
    /** The Asset Forger URL the generation returned. Short-lived; the accept re-hosts it. */
    url: string;
    /** The prompt actually sent, truncated — enough to recognise a candidate in a list. */
    prompt: string;
    /** The candidate this one was iterated from (`--from`), if any. */
    from?: string;
    /** An explicit `--reference-image-url` this candidate was steered by, if any. */
    referenceImageUrl?: string;
    createdAt: string;
}
/** The accepted reference — what every generator and forge inherits. */
export interface AcceptedReference {
    /** The URL generators are given: the re-hosted public URL, or the source URL when re-hosting failed. */
    url: string;
    /** False when re-hosting failed and `url` is the (expiring) source URL — worth re-accepting. */
    hosted: boolean;
    /** What was accepted, before any re-hosting. */
    sourceUrl: string;
    /** Absent when a bare URL was accepted rather than a generated candidate. */
    candidateId?: string;
    /** The local copy, when bytes were available to keep. */
    imagePath?: string;
    acceptedAt: string;
}
export declare function readAcceptedReference(root: string): AcceptedReference | null;
export declare function writeAcceptedReference(root: string, accepted: AcceptedReference): void;
/** Remove the accepted reference. Candidates stay — clearing a decision is not deleting the work. */
export declare function clearAcceptedReference(root: string): boolean;
export declare function readCandidate(root: string, id: string): CandidateRecord | null;
export declare function writeCandidate(root: string, record: CandidateRecord): void;
/** Every readable candidate, newest first (ids sort chronologically by construction). */
export declare function listCandidates(root: string): CandidateRecord[];
/** `ref-<yyyymmdd-hhmmss>-<4 rand>` — short enough to type, sortable by creation time. */
export declare function newCandidateId(now?: Date): string;
/** Candidate ids become file names, so anything path-shaped is refused, never sanitised. */
export declare function isSafeCandidateId(id: string): boolean;
/** The two flags every reference-aware command declares (see REFERENCE_IMAGE_FLAG / NO_REFERENCE_FLAG). */
export interface ReferenceFlagArgs {
    'reference-image-url'?: string;
    /** citty's negative boolean: `--no-reference` arrives as `false`; the flag has no positive form. */
    reference?: boolean;
}
export interface ResolvedReference {
    url?: string;
    source: 'flag' | 'disabled' | 'project' | 'none';
}
/**
 * The reference a generating command should send, in precedence order: an explicit
 * `--reference-image-url` wins outright (it IS a reference choice), `--no-reference` disables,
 * and otherwise the project's accepted reference applies — that inheritance being the whole
 * point of accepting one.
 */
export declare function resolveReferenceImageUrl(args: ReferenceFlagArgs, root: string): ResolvedReference;
/**
 * The one line a command logs when the PROJECT's reference was applied — so the agent driving
 * the CLI can see the default took effect (and knows the switch that turns it off). Explicit
 * flags echo nothing: the caller chose, and repeating their own flag back is noise.
 */
export declare function describeAppliedReference(resolved: ResolvedReference): string | null;
export declare const REFERENCE_IMAGE_FLAG: {
    readonly type: "string";
    readonly description: "Style/composition reference image URL forwarded to the image model. Overrides the accepted project reference for this call.";
};
export declare const NO_REFERENCE_FLAG: {
    readonly type: "boolean";
    readonly negativeDescription: "Do not apply the accepted project reference image (`bitmagic reference`) to this call.";
};
export declare const REFERENCE_FILE_FLAG: {
    readonly type: "string";
    readonly description: "A local image file (PNG/JPEG/WebP) to use as the reference for this call — uploaded to the game's storage first. Overrides the accepted project reference.";
};