Feat: simplify vault API and update docs

README.md

@@ -33,25 +33,92 @@ cd kvstore
 wasm-pack test --headless --firefox --features web
 ```
 
+# Rhai Scripting System
+
+A unified system for writing and executing [Rhai](https://rhai.rs/) scripts, powered by shared Rust core logic. Supports both local CLI execution and secure browser extension use, with the same business logic compiled to WebAssembly.
+
+---
+
+## Project Goals
+- **Write and run Rhai scripts** both locally (CLI) and in the browser (extension).
+- **Reuse the same Rust core logic** (vault, evm_client) across all platforms.
+- **Sandboxed, secure script execution** in both native and WASM environments.
+
+---
+
+## Architecture Overview
+
+- **Shared Rust Crates:**
+  - `vault/` and `evm_client/` implement business logic and expose APIs to Rhai.
+  - All logic is reusable in both native and WASM builds.
+- **CLI Tool (`cli/`):**
+  - Runs Rhai scripts from files or stdin using the shared core.
+  - Outputs results to the terminal.
+- **WebAssembly Module (`wasm/`):**
+  - Exposes `run_rhai(script: &str) -> String` via `wasm-bindgen`.
+  - Usable from browser JS and the extension.
+- **Browser Extension (`browser_extension/`):**
+  - UI for entering and running Rhai scripts securely in the browser.
+  - Loads the WASM module and displays results.
+- **Web App Integration:**
+  - Trusted web apps can send scripts to the extension for execution (via postMessage or WebSocket, with strict origin checks).
+
+---
+
+## Usage
+
+### CLI
+```
+sal-cli run my_script.rhai
+# or
+cat my_script.rhai | sal-cli run
+```
+
+### Browser/Extension
+- Enter Rhai code in the extension popup or trusted website.
+- Extension loads the WASM module and calls `run_rhai(script)`.
+- Result is displayed in the UI.
+
+---
+
+## Security
+- All script execution is sandboxed via Rhai + WASM.
+- Only accepts input from:
+  - Extension popup UI
+  - Approved websites (via content script)
+  - Trusted backend server (if using WebSocket)
+- Strict origin and input validation.
+- No internal APIs exposed beyond `run_rhai(script)`.
+
+---
+
 ## Directory Structure
 ```
 .
 ├── kvstore/      # Key-value store trait and backends
-├── vault/        # Cryptographic vault
-├── evm_client/   # EVM RPC client
-├── cli_app/      # CLI (planned)
-├── web_app/      # Web app (planned)
-├── docs/         # Architecture docs
+├── vault/        # Cryptographic vault (shared core)
+├── evm_client/   # EVM RPC client (shared core)
+├── cli/          # Command-line tool for Rhai scripts
+├── wasm/         # WebAssembly module for browser/extension
+├── browser_extension/  # Extension source
+├── docs/         # Architecture & usage docs
 └── README.md
 ```
 
+---
+
 ## Roadmap
 - [x] Unified async trait for key-value storage
 - [x] Native and WASM backends for kvstore
-- [ ] Cryptographic vault with password-protected keyspace
-- [ ] EVM client with vault integration
-- [ ] CLI and web app targets
-- [ ] Full end-to-end integration
+- [x] Shared Rust core for vault and evm_client
+- [x] WASM module exposing `run_rhai`
+- [ ] CLI tool for local Rhai script execution
+- [ ] Browser extension for secure script execution
+- [ ] Web app integration (postMessage/WebSocket)
+- [ ] Full end-to-end integration and security review
+
+---
 
 ## License
 MIT OR Apache-2.0
+