@letterblack/lbe-sdk 0.4.1 → 0.4.2

package/README.md

@@ -1,5 +1,7 @@
 <div align="center">
 
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/logo.svg" width="100" alt="LetterBlack logo"/>
+
 # `@letterblack/lbe-sdk`
 
 **Local-first AI execution governance.**  
@@ -14,38 +16,33 @@ Sandboxed writes · Audit · Rollback · MCP · WASM engine
 
 ---
 
+## What LBE is
+
+LBE is a local SDK that enforces a cryptographic policy gate between an AI agent and your system. It installs as an npm package, runs entirely in your process, and requires no external service, cloud connection, or hosted API. Every action an agent proposes passes through the validation engine before anything executes. Nothing phones home.
+
+---
+
+## The problem
+
+AI agents can write files, run shell commands, and modify your system — and most frameworks let them do it without any gate.
+
+There is no policy asking "is this agent allowed to do this?" There is no audit trail recording what happened. There is no rollback if it goes wrong. If an agent overwrites a config file, deletes the wrong directory, or runs a command it shouldn't — you find out after the fact, with no record and no recovery.
+
+LBE is the enforcement layer that sits between an AI agent and your system. Every action the agent proposes must pass a cryptographic validation pipeline before anything executes. If it fails — nothing runs, nothing changes, and the denial is logged. If it passes — the action executes under a governed adapter, a hash-chained audit entry is written, and rollback state is saved.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/storyboard-deny.png" width="680" alt="Rogue agent blocked: bypass attempt denied, shell untouched, filesystem unchanged, audit sealed"/>
+</div>
+
+---
+
 ## How it works
 
-```
-  AI Agent
-     │
-     │  propose action
-     ▼
-┌─────────────────────────────────────┐
-│           @letterblack/lbe-sdk      │
-│                                     │
-│  ┌─────────────────────────────┐    │
-│  │      WASM Engine            │    │
-│  │  schema → timestamp → key   │    │
-│  │  → signature → rate-limit   │    │
-│  │  → nonce → policy           │    │
-│  └────────────┬────────────────┘    │
-│               │ ok / deny           │
-│  ┌────────────▼────────────────┐    │
-│  │   Adapter (file / shell)    │    │
-│  └────────────┬────────────────┘    │
-│               │                     │
-│  ┌────────────▼────────────────┐    │
-│  │   Audit log  ·  Rollback    │    │
-│  └─────────────────────────────┘    │
-└─────────────────────────────────────┘
-     │
-     │  result + audit entry
-     ▼
-  Your app
-```
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/architecture.svg" width="680" alt="LBE SDK architecture diagram"/>
+</div>
 
-Everything runs on your machine. No hosted service. No data leaves.
+Every action proposal from an agent is validated across 7 stages — schema, timestamp, key lifecycle, Ed25519 signature, rate limit, nonce deduplication, and policy — before the adapter executes anything. All 7 stages run inside the compiled WASM engine. A denial at any stage stops execution immediately and writes an audit entry. No cloud. No data leaves the machine.
 
 ---
 
@@ -67,7 +64,7 @@ npm install @letterblack/lbe-sdk
 
 ## Quick Start
 
-### Sandbox (simple)
+### Sandbox
 
 ```js
 import { sandbox } from "@letterblack/lbe-sdk";
@@ -152,31 +149,6 @@ npx lbe-mcp                         # Start MCP server on stdio
 
 ---
 
-## API
-
-### `sandbox(root, opts?)`
-
-| Option | Default | Description |
-|---|---|---|
-| `audit` | `false` | Record governed operations to the local audit log |
-| `rollback` | `false` | Back up before writes; restore on failure |
-| `state` | `'local'` | `'local'`, `'workspace'`, or custom adapter |
-
-### `createLBE(options)`
-
-| Option | Description |
-|---|---|
-| `rootDir` | Workspace root |
-| `secretKey` | Ed25519 signing key (base64) |
-| `keyStore` | Trusted key registry |
-| `policy` | Inline policy object |
-| `state` | State storage mode |
-| `logLevel` | `DEBUG` · `INFO` · `WARN` · `ERROR` |
-
-Returns: `execute()` · `writeFile()` · `readFile()` · `exportLogs()`
-
----
-
 ## Validation pipeline
 
 Every execution proposal passes 7 stages inside the compiled WASM engine:
@@ -194,8 +166,26 @@ Every execution proposal passes 7 stages inside the compiled WASM engine:
     execute  ──▶  audit entry  ──▶  rollback state
 ```
 
-All 7 stages execute inside `runtime/lbe_engine.wasm`.  
-The JS layer handles file IO, adapter dispatch, and the public API only.
+All 7 stages execute inside `runtime/lbe_engine.wasm`. The JS layer handles file IO, adapter dispatch, and the public SDK surface only.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/Letterblack0306/letterblack-Lockstep-boundry-engine/main/assets/storyboard-allow.png" width="680" alt="Trusted agent approved: identity confirmed, policy passed, governed write executed, audit chain extended"/>
+</div>
+
+---
+
+## SDK API status
+
+The public SDK surface is intentionally minimal in v0.4.0.
+
+Current stable entry points:
+- `sandbox(root, opts?)`
+- `createLBE(options)`
+- `lbe.execute(proposal)`
+- `lbe.readFile(path)`
+- `lbe.writeFile(path, content)`
+
+Expanded API documentation will be published after the runtime contract stabilizes.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letterblack/lbe-sdk",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Commercial SDK distribution for the Lockstep Boundary Engine.",
   "type": "module",
   "main": "dist/index.js",