/**
 * Per-folder sidecar carrying an optional `display_name` override and a stable
 * folder `id`. Lives inside the folder itself so it travels atomically with FS
 * rename / move / cross-repo transfer — the same way an entity .md file's
 * frontmatter travels with the file.
 *
 * The `id` is assigned eagerly in mutation paths (folder creation); reads never
 * generate one. Callers that don't find an id fall back to a path-based key.
 */
export declare const FOLDER_SIDECAR = ".studiograph-folder.json";
export interface FolderSidecarData {
    display_name?: string;
    id?: string;
}
export declare function folderSidecarPath(absDir: string): string;
/**
 * Read the full sidecar object for a folder, or null when the sidecar is
 * absent / unreadable / malformed. Only the recognized fields are surfaced.
 */
export declare function readFolderSidecarData(absDir: string): FolderSidecarData | null;
/** Read just the display_name override, or null. (Back-compat helper.) */
export declare function readFolderSidecar(absDir: string): string | null;
/** Read just the stable folder id, or null when unassigned. */
export declare function readFolderSidecarId(absDir: string): string | null;
/**
 * Merge-safe write: reads the existing sidecar, applies the patch, and writes
 * the result — so writing one field never clobbers the other. A field present
 * in `patch` but empty/undefined is removed; a field absent from `patch` is
 * left untouched. If the merge leaves the sidecar empty, the file is removed.
 * Returns the sidecar path (for git staging), or null when the file was
 * removed because nothing remained.
 */
export declare function writeFolderSidecarData(absDir: string, patch: FolderSidecarData): string | null;
/** Write/merge a display_name override (preserves any existing id). */
export declare function writeFolderSidecar(absDir: string, displayName: string): string;
export declare function removeFolderSidecar(absDir: string): string | null;
