The field guide
A little help
with your vault.
Explore, launch and protect your projects with the current workspace. This guide reflects ProjectVault 1.19.2.
ProjectVault is in development for macOS 14 and later. There is no public download linked yet. For availability or help, email Zach about ProjectVault.
Start with your folders
- Open ProjectVault and use the Connect a project folder button in the toolbar. Select a development folder. Discovery reads your projects without enabling uploads.
- Explore your collection using Skill tree, Constellation, Collection or List. Select a project for its action menu; choose Backup Vault for its GitHub and ZIP controls.
- Choose GitHub, ZIP snapshots, or both. They have independent schedules and verification states.
Set up GitHub backups
- Install Git through Apple’s Command Line Tools. In Settings → GitHub, connect with your Mac’s SSH setup or an optional API token.
- Review the detected GitHub destination. Attach an existing repository or explicitly create a private one. Repository setup uploads nothing.
- Use Choose branch… to approve a working branch and enable backups. In Backup Vault, review Allow commit & push, then run a backup or choose a schedule.
- Look for the verified commit and timestamp. A connection or coloured icon alone is not proof of a current backup.
Existing public and private repositories on github.com are supported. A change of branch or destination may require renewed approval. Enterprise GitHub servers and LFS object backups aren’t supported.
Create a full ZIP snapshot
Open the project’s Backup Vault → ZIP tab, choose a private folder outside the project, and select Create ZIP backup now. You can schedule future snapshots separately from GitHub.
ZIPs include hidden files, ignored files, secrets and nested projects. They are not encrypted. Allow space for a staged folder copy plus the ZIP. A snapshot is verified locally before publication; cloud upload completion is separate. Old snapshots are never automatically deleted.
Back up a whole connected folder
Open a connected folder’s action menu and choose Backup Vault. Its ZIP includes every project, subfolder and file inside that location. Project filters and individual project rules do not narrow the whole-folder snapshot. Choose a private destination outside the source and select Create entire folder ZIP.
Choose your backup rhythm
Settings → Timers → Backup schedules lets you find projects and connected folders, then set independent GitHub and ZIP intervals from 1 to 168 hours. Zero means manual only. The same schedule slider is available in Backup Vault.
To keep scheduled snapshots separate from daily development, enable Use a separate scheduled backup branch in the project’s GitHub backup rules. Choose a dedicated branch name. Manual Commit & push still uses the approved working branch; scheduled snapshots leave the checkout and staging unchanged. A verified backup-branch snapshot has its own recovery action.
Open & Run
Use a project action menu or its Review/History workspace to open Open & Run. Save a live or localhost website URL, open static HTML, or confirm a detected development script in Terminal. Dependency installation is a separate action.
For Swift and Xcode projects, choose executable products or workspaces and schemes. Supported Xcode projects can build and launch on connected, configured iPhones or iPads. Mac app controls can find built and installed bundles, compare their contents, and confirm an update into your Applications folder while retaining the previous copy.
Follow work and notifications
Queue separates unread results, waiting tasks, work that needs attention, and finished actions. The notification bell opens unread results. A passive scan can step aside for requested work and then return to the queue; requests and backups finish their active item. Review the result of a failed or interrupted write before retrying it.
Review file flags and metadata
Queue findings lead back to the affected file. Use Review .gitignore… in a project’s actions to inspect shared and detected project rules. Existing rules survive, and adding an ignore rule does not remove already tracked content or its history.
Settings → Privacy sets the personal-metadata policy: based on destination visibility, warn, or require approval. A project can override it in Backup Vault → Backup rules. Credential findings always block. Approvals apply to exact contents, path, detector version and destination; they are not permission to upload an entire folder.
When a backup needs attention
- Working-branch commits with staged changes, conflicts or diverged history: review the repository in your usual Git tools, then retry. ProjectVault does not resolve conflicts or force-push.
- A file is excluded or flagged: open file review for its reason. GitHub protection covers included content only. Secret detection is heuristic and cannot guarantee that every secret is found.
- GitHub verification fails: check the account, destination, connection and branch permissions. A successful local commit can still need a push.
- A ZIP fails: check available disk space, destination availability and whether files changed during the copy. Use a destination outside the source folder.
- A schedule doesn’t run: check global pause, project settings, network access and whether the app is running. Background operation and launch at login are optional.
Recover into a fresh folder
Use Recover from GitHub into a new folder to clone the configured branch and check out the last verified commit. Existing destination folders are rejected. Unpushed or excluded files cannot be recovered from GitHub.
For ZIP recovery, choose Show ZIP and extract with Finder to a new location. Linked Git worktrees need separate protection for the main repository’s external object store.
Get in touch
Email index-hearty6c@icloud.com with your macOS version, ProjectVault version, the action you tried, and the error shown. Remove tokens, private paths and source code from screenshots or logs before sharing.