Recovery bundles

Open File > Catalogs and recovery…. The dialog has three panes, chosen from the column on the left, the way Preferences and this guide work. This catalog shows the one in use, its path, its size, how much of that is thumbnail cache and Show on disk, along with New catalog, Open catalog, Move catalog and Import into this one. Backup and recovery holds the three controls described below. Catalogs this computer knows lists every catalog you have opened. Each control says beside it what it does, and the result of the last operation appears under whichever pane you are in, so a job started in one is still reported after you move to another.

Catalogs this computer knows

This is the full history, not just the ten the File menu offers, with the one in use ticked and any whose file is missing marked. Switch opens one. Remove takes a single entry off the list and Clear list empties it; both forget where a catalog was and leave the database itself untouched, so opening it again puts it back at the top. If you keep a catalog per shoot, this is where you tidy the list.

Catalog backup

Catalog backup… writes a compact database copy at the location you choose. It preserves library records, ratings, flags, collections, catalog settings, and export and lens presets. Thumbnails are left out. It does not include the separate graph files containing edits and takes.

Automatic backups are set in Preferences > Backup > Catalog backup: Never, Daily, Weekly, Every two weeks, or Monthly (thirty days), into an existing folder you choose. Heeler checks once at each launch and backs up when at least that many days have passed since the last automatic backup, so Daily means twenty-four hours since the last one rather than a change of date. The first launch after you set a schedule backs up right away. A change to the cadence or folder takes effect at the next launch; Catalog backup… in this dialog makes a copy immediately and leaves the schedule alone.

Keep the drive connected and the folder present at launch. A missing folder is reported rather than recreated, so a disconnected drive's path is never rebuilt on the local disk; reconnect it or choose another folder, and the next launch tries again. A failure is shown in a dialog at launch that says what happened and what to do, and in the Console.

Each automatic backup is a new file, heeler-catalog-<time>.sqlite, and existing files are never overwritten or removed; clear out old copies yourself when you need the space. A copy that did not finish is left as a .partial file, never under a backup's name. A backup folder beside the catalog is allowed, but a copy on the same drive does not protect against that drive failing.

Recovery bundle

Recovery bundle… asks for a new folder name and location, then finishes pending saves for every photograph, session, settings, and presets before capturing the database. A failed save stops the bundle and names the problem. The dialog keeps its controls visible and disabled until the operation finishes.

The bundle contains:

A consistent catalog database snapshot, without thumbnails.
Saved graph documents with all their takes, including inactive takes and nested groups. Existing recovery companions are retained alongside them.
Required baked selection bases and inpaint fills referenced by saved edits. These are retained inputs, not regenerable caches.
The user preset library, including its folders. Export and lens presets travel in the database.
A manifest with the bundle schema, catalog schema, Heeler version, original locations, file sizes, SHA-256 checksums, edit counts, and source references.
An inventory of referenced photographs, File and Catalog node inputs, stack and panorama recipes and their member files. Baked stack or panorama results that are used as inputs are inventoried too.

For a trashed photograph, the current inventory expects its original filename inside .trash. If the trash index renamed it to avoid a collision, recovery can record the wrong file. Put that photograph back before capturing a bundle.

Photographs, recipes, and baked results stay at their recorded paths. Their bytes are not copied into the bundle. Keep them in your photograph backup as well. The inventory records their paths and checksums so recovery can detect a missing or changed source. A missing source produces an Incomplete result with the path, while preserving the edit files that are available.

Previews, proxies, thumbnails, depth rasters, and matte rasters are named as optional caches in the manifest and left out. Heeler rebuilds those caches when needed and their models are available. Baked selection bases and chosen inpaint fills are preserved separately because their saved pointers cannot regenerate the result. The bundle captures the active catalog and the app's saved graph and preset folders; other catalog databases require their own backup.

The bundle is written under a unique .partial staging name, synchronized, and renamed to the chosen name only after all files and the manifest are written. An existing destination is refused. A failed write leaves its .partial staging folder in place and names it in the error. It holds copies of files that still live in Heeler's own folders, the verifier refuses it, and removing it is yours to do, since Heeler deletes nothing in a folder you chose. No photograph is changed.

Verify recovery bundle

Verify recovery bundle… asks for a bundle folder. It works offline and reads the bundle and original files without restoring or modifying them. The result lists photographs, graphs, takes, presets, referenced assets, required baked inputs, and the writing app's version. Complete means the bundled files pass their size and checksum checks, the database passes its integrity check, edit counts and references agree, and all required originals still match their recorded checksums. Incomplete names missing or changed files. Unknown schemas, unsafe paths, and symbolic links inside the bundle are refused.

The same verifier runs from a terminal, with no app window, service, model, or app-data migration:

heeler-desktop recovery verify /path/to/edits.heeler-recovery

It prints a JSON report and returns exit status 0 for complete, 1 for incomplete or unreadable, and 2 for incorrect arguments.

Restore into empty app data

Quit Heeler before restoring. Keep originals at their recorded locations and create an empty destination directory. Run:

heeler-desktop recovery restore /path/to/edits.heeler-recovery /path/to/empty-app-data

Restore verifies the whole bundle and its referenced originals before copying the database, graphs, and presets. It refuses a nonempty destination and never overwrites an existing file. The restored database is named catalog.sqlite, so Heeler uses it by default when this directory is used as its app-data directory. When required baked inputs are restored, their files live under the new app data. A custom model-store preference is reset to the default so Heeler finds those inputs there. Model weights are not included. An interrupted restore may leave copied files in the destination; retain those files and retry into another empty directory. The recovery bundle stays unchanged.

There is no recovery preference or schedule to set. Each bundle uses the location you choose. Scheduled catalog backups remain database backups.