Docs & FAQ

Getting Started

What is a vault folder?

Your vault is an ordinary folder — on your device or in your cloud storage — where HomeVault keeps everything as plain text files. When you first open HomeVault you pick that folder yourself, using your phone's own file picker, from whatever locations it can already reach. Everything HomeVault knows about your home is in that folder, and nowhere else.

Do I have to use a particular cloud service?

No — and HomeVault does not connect to one. It reads and writes files in a folder, and your phone's file picker decides which folders are on offer. If a service is installed on your phone and shows up in that picker, HomeVault can use it. There is nothing to sign in to.

On iPhone and iPad, use iCloud Drive or Dropbox. Those are the two that let an app choose a folder. OneDrive and Google Drive appear in the Files picker but are grayed out: their Files integrations do not offer folders to other apps, and no app can work around that. Dropbox is the one to choose if you want to share the vault with someone who is not on Apple devices.

On Android the picker offers whatever you have installed. You can also keep the vault on the device itself — just note that you won't have automatic backups.

How do I share my vault with my partner?

Point both devices at the same folder, and share that folder using your cloud service's own sharing. HomeVault has no sharing feature of its own because it does not need one — to the app, a shared folder is just a folder.

On iPhone, pick a folder in your own iCloud Drive or in Dropbox rather than taking the default. The default location is a container that belongs to the app: convenient, and backed up, but it cannot be shared with anyone outside your Apple Family. Dropbox is the better choice when the other person is not on Apple devices — OneDrive and Google Drive cannot be picked on iOS at all.

If two people edit the same item at once, HomeVault will not overwrite the other person's copy. The write is refused, your edit is kept on your device, and the clash is recorded. Choosing which version to keep is currently something you do by hand.

Items & Attachments

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.

Tasks & Checklists

I have eight smoke detectors. How do I avoid eight reminders?

Keep them as eight records and put their tasks in one checklist.

Each detector is its own item, in its own room, with its own service history — that is what lets you answer “when did I last do the one in the hall?” But changing all the batteries is one job, so the tasks belong together.

Add the first detector and give it a task — “change battery”, repeating yearly. Put that task in a checklist called something like “Smoke detector batteries”. Then open the item, choose duplicate, and tick the other seven rooms. You get eight records and eight tasks, all already in that checklist, and one reminder when they come due.

Service one out of sequence and it moves to its own anniversary and reminds you separately. Reminders follow the dates, not the checklist — so a group that drifts apart stops behaving like a group, which is usually what you want.

The same shape works for anything you own several of: toilets, bathroom sinks, air filters on different floors, two water heaters installed years apart.

What does duplicating an item copy?

Everything that describes the model, and nothing that identifies the unit.

Copied: name, category, room (the one you pick), make, model, notes, warranty expiry, and purchase date, price and store — an eight-pack was bought once, at one price, on one day. Any maintenance tasks come across too, keeping their schedule, due date and checklist.

Not copied: serial number, warranty claim reference, service history, photos and attachments. A serial is the one field where a copy is worse than a blank: it is not a template you can edit down, and unlike a wrong date it never looks wrong — so seven of your eight detectors would quietly carry the first one's number until a warranty claim went bad.

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.

Encryption

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.

Data & Schema

What format are vault files stored in?

Plain text — JSON, UTF-8, one file per record. 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 are stored flat, one file each, as attachments/{uuid}.{ext}. At the root, vault.meta.json records the schema version and encryption settings, and index.json holds a plain summary of every record so the app can build its lists without opening each file in turn.

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_storage. It includes JSON Schema definitions for all file types, field descriptions, and example files.

Troubleshooting

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.