chore(8.0): final pre-RC1 sweep — API consistency, named errors, orphans, zero-cast codebase

docs/architecture/storage-architecture.md

@@ -239,37 +239,30 @@ await brain.storage.withLock('resource-id', async () => {
 
 ## Migration and Backup
 
-### Export Data
+Backup and restore go through the Db API — see
+[Snapshots & Time Travel](../guides/snapshots-and-time-travel.md) for the full
+recipe book.
+
+### Snapshot (backup)
 ```typescript
-// Export entire database
-const backup = await brain.export({
-  format: 'json',
-  includeVectors: true,
-  includeIndexes: false
-})
+// Instant, self-contained snapshot (hard links on filesystem storage)
+const db = brain.now()
+await db.persist('/backups/2026-06-11')
+await db.release()
 ```
 
-### Import Data
+### Restore
 ```typescript
-// Import from backup
-await brain.import(backup, {
-  mode: 'merge',        // or 'replace'
-  validateSchema: true
-})
+// Replace the store's entire state from a snapshot (destructive — confirm required)
+await brain.restore('/backups/2026-06-11', { confirm: true })
 ```
 
-### Storage Migration
+### Move to a new directory
 ```typescript
-// Migrate between storage types
-const oldBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './old' } })
-const newBrain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './new' } })
-
-await oldBrain.init()
-await newBrain.init()
-
-// Transfer all data
-const data = await oldBrain.export()
-await newBrain.import(data)
+// A snapshot directory is a complete store: restore it into a fresh brain
+const brain = new Brainy({ storage: { type: 'filesystem', rootDirectory: './new' } })
+await brain.init()
+await brain.restore('/backups/2026-06-11', { confirm: true })
 ```
 
 ## Performance Tuning