Feat: simplify vault API and update docs

docs/kvstore.md

@@ -0,0 +1,123 @@
+# kvstore Crate Overview
+
+`kvstore` is a runtime-agnostic, async key-value storage crate designed for both native (using `sled`) and WASM/browser (using IndexedDB via the `idb` crate) environments. It provides a unified API for all platforms, enabling seamless storage abstraction for Rust applications.
+
+---
+
+## Table of Contents
+- [Summary](#summary)
+- [Main Components](#main-components)
+- [Supported Environments](#supported-environments)
+- [Quickstart & Usage Examples](#quickstart--usage-examples)
+- [API Reference](#api-reference)
+- [More Information](#more-information)
+
+---
+
+## Summary
+The `kvstore` crate defines an async trait for key-value storage, with robust implementations for native and browser environments. It is the storage backend for higher-level crates such as `vault`.
+
+---
+
+## Main Components
+- **KVStore Trait**: Async interface for key-value operations (`get`, `set`, `remove`, `contains_key`, `keys`, `clear`).
+- **NativeStore**: Native backend using `sled` (requires Tokio runtime).
+- **WasmStore**: WASM/browser backend using IndexedDB via the `idb` crate.
+- **KVError**: Error type covering I/O, serialization, encryption, and backend-specific issues.
+
+---
+
+## Supported Environments
+- **Native:** Uses `sled` for fast, embedded storage. Blocking I/O is offloaded to background threads using Tokio.
+- **Browser (WASM):** Uses IndexedDB via the `idb` crate. Fully async and Promise-based.
+
+---
+
+## Quickstart & Usage Examples
+
+### Native Example
+```rust
+use kvstore::{KVStore, NativeStore};
+
+#[tokio::main]
+async fn main() {
+    let store = NativeStore::open("/tmp/mydb").unwrap();
+    store.set("foo", b"bar").await.unwrap();
+    let val = store.get("foo").await.unwrap();
+    println!("Got: {:?}", val);
+}
+```
+
+### WASM/Browser Example
+```rust
+// In a browser/WASM environment:
+use kvstore::{KVStore, WasmStore};
+
+// Must be called from an async context (e.g., JS Promise)
+let store = WasmStore::open("mydb").await.unwrap();
+store.set("foo", b"bar").await.unwrap();
+let val = store.get("foo").await.unwrap();
+// Use the value as needed
+```
+
+---
+
+## API Reference
+
+### KVStore Trait
+```rust
+#[async_trait]
+pub trait KVStore {
+    async fn get(&self, key: &str) -> Result<Option<Vec<u8>>>;
+    async fn set(&self, key: &str, value: &[u8]) -> Result<()>;
+    async fn remove(&self, key: &str) -> Result<()>;
+    async fn contains_key(&self, key: &str) -> Result<bool>;
+    async fn keys(&self) -> Result<Vec<String>>;
+    async fn clear(&self) -> Result<()>;
+}
+```
+
+### NativeStore
+```rust
+pub struct NativeStore { /* ... */ }
+
+impl NativeStore {
+    pub fn open(path: &str) -> Result<Self>;
+    // Implements KVStore trait
+}
+```
+
+### WasmStore
+```rust
+pub struct WasmStore { /* ... */ }
+
+impl WasmStore {
+    pub async fn open(name: &str) -> Result<Self>;
+    // Implements KVStore trait
+}
+```
+
+### Error Handling
+```rust
+#[derive(Debug, Error)]
+pub enum KVError {
+    Io(std::io::Error),
+    KeyNotFound(String),
+    StoreNotFound(String),
+    Serialization(String),
+    Deserialization(String),
+    Encryption(String),
+    Decryption(String),
+    Other(String),
+}
+```
+
+---
+
+## More Information
+- For architecture and design, see [`architecture.md`](architecture.md)
+- For integration examples, see [`build_instructions.md`](build_instructions.md)
+
+---
+
+*For advanced usage, backend customization, and WASM integration, see the linked documents above.*