Library backups

Astramar stores your phrase library locally in a versioned persistence envelope. Rolling recovery backups help with accidents; they are not a substitute for your own exports or system backups.

Technical paths still use the PhrasePilot identity. The live library is normally at:

~/Library/Application Support/PhrasePilot/data.json

Do not hand-edit that file. Prefer in-app export, import, and recovery controls.

Export and import (`.phrasepilot`)

Open Settings → Library.

Export (included for Free and Pro personal libraries):

Export Library — full library
Export Folder — selected folder and its subfolders
Export Phrase — selected phrase only

Import (Free):

Import Library — into the library root
Import Into Folder — into the selected folder
Restore Starter Guide — re-adds a fresh starter examples folder without overwriting your existing content

Imports show a review sheet (folder, phrase, and shared-variable counts, conflicts, possible duplicates) with:

Keep Both
Replace Existing
Skip Duplicates

Keep an independent .phrasepilot copy outside Application Support before testing pre-release builds or making large library changes.

Rolling backups

Astramar validates library candidates before replacing the live file. It keeps up to five distinct validated rolling backups under:

~/Library/Application Support/PhrasePilot/Recovery/Backups

Supported library size for responsive everyday use is hardened around 10,000 phrases. Larger libraries may work but are outside the supported responsiveness targets.

Recovery window

If the live library is unreadable, uses a future schema, or contains invalid JSON, Astramar blocks normal startup instead of inventing starter data. The recovery window can:

Restore a selected / latest validated backup (current live bytes are preserved in quarantine first)
Import a .phrasepilot or compatible JSON transfer after validation
Reveal Recovery Files in Finder
Retry Preservation if quarantine copy failed
Start Empty… only after explicit confirmation (original must be quarantined first)

Recovery actions stay visible in a sticky footer so Restore / Import / Start Empty remain reachable while longer explanations scroll.

If the app says the library was written by a newer Astramar / PhrasePilot, quit without replacing it and install a compatible build. An older app will not silently rewrite a newer live file.

After a successful recovery, quit and reopen the app.

Save failures

If an ordinary save fails, the UI stops claiming automatic saves succeeded. Use Retry Save after fixing disk space or permissions, or Reveal Library Folder. On Quit while a save is still failing, you can Quit Without Saving, Retry Save, or Cancel.

Diagnostic summary (safe for support)

Settings → Library → Export Diagnostic Summary… writes a metadata-only JSON file. Review it before sharing.

It can include app/macOS versions, library load/save status, Accessibility state, schema/checksum metadata, and bounded timeout categories. It does not include phrase text, titles, templates, clipboard contents, tokens, scripts, or a usable library copy.

Never attach data.json or .phrasepilot exports to a public report unless you intend to share that private content.