Docs — HomeVault

Getting Started

What is a vault folder?: Your vault is a folder on your device or in your cloud storage where HomeVault stores all of your data as plain JSON files. When you first open HomeVault, you choose where this folder lives — on-device, in iCloud Drive, Google Drive, or Dropbox. Everything HomeVault knows about your home is in that folder, and nowhere else.
Which cloud storage should I use?: Any option works. iCloud Drive is the simplest choice for iPhone/iPad users. Google Drive works well if you use Android or want cross-platform access. Dropbox is a good choice if you already have an account and want desktop access to your vault files. You can also keep the vault on-device if you prefer not to use cloud storage at all — just note that you won't have automatic backups.
How do I share my vault with my partner?: Point both devices at the same cloud folder. In iCloud Drive, you can share a folder with another Apple ID. In Google Drive or Dropbox, share the vault folder with their account. Both people will see and edit the same items. HomeVault doesn't have built-in conflict resolution — if two people edit the same item at the same moment, whichever save lands last wins, so it works best for households where edits are infrequent.

What's the difference between plaintext and sensitive fields?: Plaintext fields — name, brand, room, category, notes, and dates — are stored unencrypted in items/{uuid}.json and are always readable without a passphrase. Sensitive fields — serial number, purchase price, and receipt attachments — can optionally be encrypted. When encryption is on, these are stored in a separate items/{uuid}.secret.json sidecar file and require your passphrase to read.
How large can attachments be?: HomeVault doesn't enforce an attachment size limit, but your cloud storage provider's file size limits apply. For photos, HomeVault stores the original file you attach without re-encoding it. Keeping receipts as compressed PDFs and photos under a few megabytes each will keep your vault folder a manageable size over time.
How do I set a primary photo?: In the item detail view, tap an attachment photo and choose "Set as primary photo." The primary photo is shown as the item's thumbnail in list and grid views.

How does recurring task scheduling work?: Recurring tasks in HomeVault use an interval from completion model. When you mark a task done, the next due date is calculated from the actual completion date — not from the original schedule. If your HVAC filter is due every 90 days and you complete it a week late, the next reminder is 90 days from when you actually did it. This avoids the frustration of being immediately overdue because you did something a few days off-schedule.
What's the difference between a task and a checklist?: A task is a single maintenance action — "replace HVAC filter," "test smoke alarms." A checklist is a group of related tasks that are completed together as a unit — for example, an annual spring inspection that covers cleaning the gutters, flushing the water heater, and checking the roof. Checklists can also recur: completing all tasks in a checklist triggers the next recurrence.
What happens when all checklist tasks are completed?: The checklist is marked complete and, if it recurs, a new instance is scheduled from the completion date. The completed instance is archived in the item's maintenance history so you have a permanent record of when each run was completed.

What does optional encryption protect?: When you enable encryption and set a passphrase, HomeVault encrypts sensitive fields — serial numbers, purchase prices, and receipt attachments — using AES-256-GCM before writing them to disk. This means someone with access to your vault folder (for example, if your cloud storage is compromised) cannot read those fields without your passphrase.
What happens if I lose my passphrase?: The encrypted fields in your vault become permanently unreadable. There is no recovery mechanism — HomeVault has no servers, so there is nothing to contact for a reset. Plaintext fields (name, room, notes, dates) are not encrypted and remain accessible. Write your passphrase somewhere secure before enabling encryption.
Where is the encryption key stored?: The key is derived from your passphrase each time you unlock the vault — it is never stored anywhere on disk. HomeVault uses PBKDF2 to derive a key from your passphrase and a random salt stored in the vault folder. Without the passphrase, the salt alone is useless.

What format are vault files stored in?: Plain JSON, UTF-8, one file per item. Each item is stored as items/{uuid}.json. If you have encryption enabled for an item, its sensitive fields are stored in items/{uuid}.secret.json (AES-256-GCM encrypted). Attachments live in attachments/{uuid}/. There is also a vault.json manifest at the root.
Can I edit vault files outside the app?: Yes. The JSON format is intentionally simple and human-readable. You can open any items/{uuid}.json in a text editor and make changes — they'll appear in the app the next time it reads the vault. Just don't modify .secret.json files by hand; editing encrypted data will corrupt it.
Where can I find the full schema?: The full JSON schema for vault files is published on GitHub at github.com/admin-homevault-casa/homevault-schema. It includes JSON Schema definitions for all file types, field descriptions, and example files.

Why does the app show "Vault unavailable"?: This means HomeVault can't access the vault folder. Common causes: the cloud storage app (iCloud, Google Drive, Dropbox) is offline or hasn't finished syncing; you moved or renamed the vault folder outside the app; or the folder's permissions changed. Open your cloud storage app, wait for sync to complete, then return to HomeVault and tap "Retry."
How do I rebuild the index?: Go to Settings → Vault → Rebuild Index. HomeVault will re-scan every JSON file in your vault folder and reconstruct the in-app index from scratch. This is useful if items are missing from lists or if you've made manual edits to vault files outside the app.
What does "Locked" mean on an item?: A locked item has sensitive fields that are encrypted, and you haven't entered your passphrase in the current session. Tap the item and enter your passphrase to unlock it. Plaintext fields — name, dates, notes — are always visible even when an item is locked.