update docs

2026-04-04 08:40:17 -04:00
parent 081e4c587c
commit 0cff2069b7
18 changed files with 888 additions and 468 deletions
@@ -11,6 +11,8 @@
 - [Vault snapshots](#vault-snapshots)
 - [HDMS and extra drives](#hdms-and-extra-drives)
 - [Where to read the full story](#where-to-read-the-full-story)
+- [Where state lives on disk (mental model)](#where-state-lives-on-disk-mental-model)
+- [Passphrases, backups, and data loss](#passphrases-backups-and-data-loss)

 ---

@@ -32,6 +34,23 @@ Cryptographic details are implementation-specific; this manual stays at the beha

 ---

+## Where state lives on disk (mental model)
+
+Think in **two layers**:
+
+1. **Hyperdrive blocks** replicated through Corestore — durable bytes identified by keys and discovery topics, not by a traditional host path.
+2. **VFS paths** — what you see in the shell (**`/home/guest`**, **`/.bare/account`**, **`/mnt/...`**) as the booter merges drives and synthetic mounts.
+
+Guests can write under guest **`HOME`** and read shared system content. **Unlocked** users get a different **`HOME`** subtree and can manipulate HDMS registry entries that survive across sessions. If you are debugging “where did my file go?”, check both **`pwd`** and whether you **logged out** (which clears in-memory keys even when ciphertext remains on disk).
+
+---
+
+## Passphrases, backups, and data loss
+
+**`login --new`** creates keys derived from your passphrase. If you **forget** the passphrase, ciphertext under **`/.bare/`** is not recoverable by design. If you **lose** the personal drive replication (new machine, wiped Corestore) without exporting keys or vault snapshots, you also lose access. For operational guidance beyond this overview, read [Developer guide — Security and trust](../developer-guide/09-security-and-trust.md) and the handbook’s identity chapter.
+
+---
+
 ## Vault snapshots

 **`savevault`** and **`logout --save`** can store **encrypted snapshots** of selected paths under **`/.bare/vault/`**. Vault security depends on your **passphrase strength**, **who can replicate** your personal drive, and your **backup** practices. Treat vault blobs as sensitive ciphertext, not as a substitute for off-machine backups if you care about durability.