@biglogic/rgs 3.8.0 → 3.8.4

package/README.md

@@ -1,277 +1,286 @@
-# Argis (RGS) - Reactive Global State
+# 🚀 ARGIS (RGS) - Reactive Global State
 
-> "The Magnetar" **Atomic Precision. Immutable Safety. Zen Simplicity.**
-> The most powerful state management engine for React. Built for those who demand industrial-grade reliability with a zero-boilerplate experience.
+<div align="center">
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![version](https://img.shields.io/npm/v/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-[![downloads](https://img.shields.io/npm/dm/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
-
-![Javascript](https://img.shields.io/badge/Javascript-gray?logo=Javascript)
-![React](https://img.shields.io/badge/React-gray?logo=React)
-![TypeScript](https://img.shields.io/badge/TypeScript-gray?logo=typescript)
-![Node.js](https://img.shields.io/badge/Node.js-gray?logo=node.js)
-![Jest](https://img.shields.io/badge/Jest-gray?logo=jest)
-![Playwright](https://img.shields.io/badge/Playwright-gray?logo=playwright)
-![ESLint](https://img.shields.io/badge/Eslint-gray?logo=eslint)
-![esbuild](https://img.shields.io/badge/esbuild-gray?logo=esbuild)
+> **"Atomic Precision. Immutable Safety. Zen Simplicity."**
+> The state management engine that **won't let you fail**.
 
-![Snik](https://img.shields.io/badge/Snyk-gray?logo=Snyk)
-![Snik](https://img.shields.io/badge/Socket-gray?logo=socket)
+[![npm version](https://img.shields.io/npm/v/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
+[![npm downloads](https://img.shields.io/npm/dm/@biglogic/rgs.svg)](https://npmjs.org/package/@biglogic/rgs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-19+-61DAFB.svg)](https://react.dev/)
 
-<!-- [![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://a51.gitbook.io/rgs) -->
+</div>
 
 ---
 
-## 🌟 Why Magnetar?
+## ⚡ TL;DR - Why ARGIS (RGS) Will Change How You Code Forever
 
-We took the simplicity of **Reactive Global State (RGS)** and fused it with the architecture of a **High-Performance Kernel**. It's the only library that gives you:
+```tsx
+// One line. Zero boilerplate. Enterprise-grade power.
+const useUser = gstate({
+  name: 'Alice',
+  cart: [],
+  preferences: { theme: 'dark' }
+})
 
-- **💎 Absolute Immutability**: Powered by **Immer**. No more manual spreads. State is frozen by default.
-- **🛡️ Industrial-Grade Safety**: Deep Proxy guards that throw `Forbidden Mutation` errors if you try to bypass the kernel.
-- **🔌 Enterprise Ecosystem**: A real plugin architecture with 10+ official modules (Sync, Storage, DevTools, etc.).
-- **⚛️ Power on Demand**: Advanced async and persistence tools isolated in the `advanced` export.
-- **🏗️ Stellar Architecture**: Zero circular dependencies. Modular, clean, and 100% type-safe.
+// That's it. Use it anywhere:
+const name = useUser(s => s.name)
+const theme = useUser(s => s.preferences.theme)
 
----
+// Mutations? Just write it. Immer handles immutability automatically.
+useUser(s => {
+  s.cart.push({ id: 1, item: 'Coffee Machine', price: 99 })
+})
+```
 
-## ggtate vs useState
-
-| Feature | RGS ggtate | React useState |
-|---------|--------|----------|
-| **Global state across components** | ✅ Automatic sharing | ❌ Need Context/props |
-| **Provider wrapper** | ✅ Not needed | ❌ Required |
-| **Persistence (localStorage)** | ✅ Built-in | ❌ Manual |
-| **Data encryption** | ✅ AES-256-GCM | ❌ |
-| **Multiple namespaces/stores** | ✅ | ❌ |
-| **Plugins (Immer, Undo/Redo)** | ✅ | ❌ |
-| **Audit logging** | ✅ | ❌ |
-| **RBAC/GDPR consent** | ✅ | ❌ |
-| **SSR/Hydration** | ✅ Automatic | ❌ Manual |
-| **Computed values** | ✅ | ❌ |
-
-### When to use what?
-
-- **useState**: Local UI, single component, temporary state
-- **gstate**:
-  - Shared state across multiple components
-  - Persistent data (preferences, cart, authentication)
-  - Sensitive data (encryption)
-  - Advanced features (undo/redo, snapshots)
-  - Enterprise (audit, RBAC, GDPR)
+**Stop fighting your state management. Start building.**
 
 ---
 
-## ⚔️ The Arena: RGS vs The World
-
-|Feature|**RGS (Argis)**|Zustand|Redux Toolkit|Recoil|
-|:---|:---|:---|:---|:---|
-| **Philosophy** | **Zen State** | Minimalist | Enterprise Flux | Atomic |
-| **API Surface** | **1 Function** | Simple | Complex | Complex |
-| **Mutations** | **Magic (Immer)** | Manual Spreads | Magic (Immer) | Manual |
-| **Selectors** | ✅ **Type-Safe** | ✅ Functional | ✅ Functional | ⚠️ Selectors |
-| **Security** | 🛡️ **AES-256 + RBAC** | ❌ None | ❌ Ecosystem | ❌ None |
-| **Persistence** | 💾 **First-class** | 🔌 Middleware | 🔌 Middleware | 🔌 Effects |
-| **Async** | ✅ **Atomic** | ✅ Async/Await | ✅ Thunks | ✅ Suspense |
-| **Local-First Sync** | ✅ **Built-in** | ❌ None | ❌ None | ❌ None |
-| **Bundle Size** | **~2kB** | ~1kB | >10kB | >20kB |
+## 🎯 Why Developers Are **Obsessed** With ARGIS (RGS)
 
-> **RGS** is the only library on the market that treats **Security** and **Persistence** as first-class citizens.
+| Feature | Other Libraries | ARGIS (RGS) |
+|---------|----------------|--------------|
+| **API Complexity** | 10+ functions, providers, reducers | **1 function** - `gstate()` |
+| **Immutability** | Manual spreads, Redux boilerplate | **Automatic** - Powered by Immer |
+| **Security** | None | **AES-256 + RBAC + GDPR** built-in |
+| **Persistence** | Manual localStorage/sessionStorage | **First-class** - Auto-save anywhere |
+| **Offline/Cloud Sync** | Non-existent | **Local-First + Cloud Sync** included |
+| **Bundle Size** | 10-50KB+ | **~2KB** minimal / **~32KB** full |
+| **Type Safety** | Partial | **100% TypeScript** out of the box |
 
----
+### 🔥 The Truth About State Management
 
-### Installation
+Most libraries make you **choose** between:
+- ✗ Simplicity vs Power
+- ✗ Security vs Speed
+- ✗ Offline vs Cloud
 
-```shell
-npm install @biglogic/rgs
-```
+**ARGIS (RGS) gives you ALL of it.**
 
 ---
 
-### Examples and guide
+## 🏆 RGS vs The Competition
 
-**[github.com/BigLogic-ca/rgs](https://github.com/BigLogic-ca/rgs)**
+| Feature | **RGS (Argis)** | Zustand | Redux Toolkit | Recoil | Jotai |
+|---------|:---:|:---:|:---:|:---:|:---:|
+| **Philosophy** | Zen State | Minimalist | Enterprise Flux | Atomic | Atomic |
+| **API Surface** | **1 Function** | Simple | Complex | Complex | Simple |
+| **Mutations** | **Magic (Immer)** | Manual | Magic | Manual | Manual |
+| **Security** | 🛡️ **AES-256 + RBAC** | ❌ | ❌ | ❌ | ❌ |
+| **Persistence** | 💾 **First-class** | 🔌 | 🔌 | 🔌 | 🔌 |
+| **Local-First Sync** | ✅ **Built-in** | ❌ | ❌ | ❌ | ❌ |
+| **Bundle Size** | **~2KB/32KB** | ~1KB | >10KB | >20KB | ~3KB |
 
----
-
-## 🏗️ Architecture
-
-```mermaid
-graph TB
-    subgraph API
-        A[gstate] --> D[IStore]
-        B[useStore] --> D
-        C[createStore] --> D
-    end
+> **RGS is the ONLY library treating Security and Persistence as first-class citizens.**
 
-    D --> E[Storage Adapter]
-    D --> F[Immer Proxy]
-    D --> G[Plugins]
-    D --> H[Security]
-    D --> I[Async Store]
+---
 
-    E --> J[local]
-    E --> K[session]
-    E --> L[memory]
+## 🚀 Installation
 
-    G --> M[UndoRedo]
-    G --> N[Sync]
-    G --> O[Schema]
-    G --> P[Analytics]
+```bash
+# The fastest way to upgrade your React app
+npm install @biglogic/rgs
 ```
 
-### Core Components
+```bash
+# Or with pnpm
+pnpm add @biglogic/rgs
 
-| Component | Description |
-|-----------|-------------|
-| **gstate()** | Creates store + hook in one line |
-| **useStore()** | React hook for subscribing to state |
-| **createStore()** | Classic store factory |
-| **IStore** | Core interface with get/set/subscribe |
-| **StorageAdapters** | local, session, memory persistence |
-| **Plugins** | Immer, Undo/Redo, Sync, Schema, etc. |
-| **Security** | Encryption, RBAC, GDPR consent |
+# Or with yarn
+yarn add @biglogic/rgs
+```
 
 ---
 
-## Requirements
-
-- **React 16.8+** (for hooks support)
-- **React DOM**
-
-## ⚡ Zero-Boilerplate Quickstart
-
-### Path A: The Zen Way (Modular)
+## 🎮 Quick Start - 30 Seconds to Glory
 
-Best for modern applications. Clean imports, zero global pollution, **Type-Safe**.
+### The Zen Way (Recommended)
 
 ```tsx
 import { gstate } from '@biglogic/rgs'
 
-// 1. Create a typed store hook
-const useCounter = gstate({ count: 0, user: { name: 'Alice' } })
-
-// 2. Use with Type-Safe Selectors (Preferred)
-const count = useCounter(state => state.count)
-const userName = useCounter(state => state.user.name)
+// ONE line creates a typed store hook
+const useStore = gstate({
+  count: 0,
+  user: { name: 'Alice', email: 'alice@example.com' }
+})
 
-// OR use string keys (Legacy)
-const [count, setCount] = useCounter('count')
+function Counter() {
+  // Type-safe selectors - the React way
+  const count = useStore(s => s.count)
+  const userName = useStore(s => s.user.name)
+
+  // Direct mutations - just write JavaScript
+  const increment = () => useStore(s => { s.count++ })
+
+  return (
+    <div>
+      <h1>Hello, {userName}!</h1>
+      <p>Count: {count}</p>
+      <button onClick={increment}>+1</button>
+    </div>
+  )
+}
 ```
 
-### Path B: The Classic Way (Global)
-
-Best for shared state across the entire application.
+### The Classic Way (Global Store)
 
 ```tsx
-// 1. Initialize once
 import { initState, useStore } from '@biglogic/rgs'
-initState({ namespace: 'app' })
 
-// 2. Use anywhere
+// Initialize once at app root
+initState({ namespace: 'myapp' })
+
+// Use anywhere in your app
 const [user, setUser] = useStore('user')
+const [theme, setTheme] = useStore('theme')
 ```
 
 ---
 
-## 🛡️ Security Architecture
+## 🛡️ Enterprise-Grade Security (No Extra Code)
 
-RGS includes enterprise-grade security features to protect your application and user data:
+### AES-256-GCM Encryption
 
-### ReDoS Protection
-All regex patterns used in RBAC permission matching include timeout protection (100ms) to prevent Regex Denial of Service attacks.
+```tsx
+// Your sensitive data is encrypted automatically
+const useAuth = gstate({
+  token: 'jwt-token-here',
+  refreshToken: 'refresh-token'
+}, { encoded: true })  // 🔐 AES-256-GCM encryption enabled
+```
 
-### Safe UUID Generation
-Falls back to cryptographically secure random UUID generation when native `crypto.randomUUID()` is unavailable.
+### RBAC (Role-Based Access Control)
 
-### Input Validation
-- **Storage Key Validation**: Keys are validated against `/^[a-zA-Z0-9_.-]+$/` to prevent injection attacks
-- **Value Sanitization**: All persisted values are sanitized to prevent XSS attacks
+```tsx
+const store = gstate({
+  adminPanel: { users: [], settings: {} },
+  userProfile: {}
+}, {
+  rbac: {
+    admin: ['adminPanel', 'userProfile'],
+    user: ['userProfile'],
+    guest: []
+  }
+})
 
-### Encryption
-- **AES-256-GCM**: Industry-standard encryption for sensitive data
-- **Encoded Mode**: Use `{ encoded: true }` option for base64-encoded storage (note: renamed from `secure` for clarity)
+// Only admins can touch adminPanel
+store.set('adminPanel', { users: ['new'] }) // ✅ Works for admins
+```
 
 ### GDPR Compliance
-- Consent management system
-- Data export (`exportData()`)
-- Data deletion (`deleteData()`)
 
-### Development vs Production
-Global `gstate` exposure to window is only enabled in development mode (`NODE_ENV !== 'production'`).
+```tsx
+// Export all user data (GDPR requirement)
+store.exportData()  // Returns JSON of all stored data
+
+// Delete all user data (GDPR "right to be forgotten")
+store.deleteData()
+```
 
 ---
 
-## 📚 Quick Examples
+## 💾 Persistence That Just Works
+
+### Built-in Storage Adapters
 
 ```tsx
-const store = gstate({ theme: 'dark' }, "my-app")
-```
+// localStorage (default) - survives browser restart
+const useSettings = gstate({ theme: 'dark' }, { persist: true })
 
-### Encryption
+// sessionStorage - survives page refresh but not tab close
+const useSession = gstate({ temporary: 'data' }, { storage: 'session' })
 
-```tsx
-const secureStore = gstate({ token: 'xxx' }, { encoded: true })
+// Memory only - for ephemeral data
+const useMemory = gstate({ cache: [] }, { storage: 'memory' })
+
+// IndexedDB - for GB-scale data
+const useBigData = gstate({ dataset: [] })
+store._addPlugin(indexedDBPlugin({ dbName: 'my-app-db' }))
 ```
 
-### Undo/Redo
+---
+
+## 🔌 Plugins Ecosystem - Extend Without Limits
+
+RGS comes with **11+ official plugins** ready to supercharge your app:
+
+| Plugin | Purpose | One-Liner |
+|--------|---------|-----------|
+| `undoRedoPlugin` | Time travel through state | `store.undo()` / `store.redo()` |
+| `syncPlugin` | Cross-tab sync (no server) | `store._addPlugin(syncPlugin(...))` |
+| `indexedDBPlugin` | GB-scale storage | `store._addPlugin(indexedDBPlugin(...))` |
+| `cloudSyncPlugin` | Cloud backup & sync | `store.plugins.cloudSync.sync()` |
+| `devToolsPlugin` | Redux DevTools | `store._addPlugin(devToolsPlugin(...))` |
+| `immerPlugin` | Mutable-style updates | `store.setWithProduce('key', fn)` |
+| `snapshotPlugin` | Save/restore checkpoints | `store.takeSnapshot('backup')` |
+| `schemaPlugin` | Runtime validation | `store._addPlugin(schemaPlugin(...))` |
+| `guardPlugin` | Transform on set | `store._addPlugin(guardPlugin(...))` |
+| `analyticsPlugin` | Track changes | `store._addPlugin(analyticsPlugin(...))` |
+| `debugPlugin` | Console access (DEV) | `window.gstate.list()` |
+
+### Undo/Redo - Never Lose Work
 
 ```tsx
-const store = gstate({ count: 0 })
+import { undoRedoPlugin } from '@biglogic/rgs'
+
+const store = gstate({ text: '' })
 store._addPlugin(undoRedoPlugin({ limit: 50 }))
 
-store.undo()
-store.redo()
+// User makes changes...
+store.set('text', 'Hello World')
+store.set('text', 'Hello Universe')
+
+// Oops! Let's go back
+store.undo()  // Returns to 'Hello World'
+store.redo()   // Returns to 'Hello Universe'
 ```
 
-### Cross-Tab Sync
+### Cross-Tab Sync - Real-Time Everywhere
 
 ```tsx
+import { syncPlugin } from '@biglogic/rgs/advanced'
+
 const store = gstate({ theme: 'light' })
 store._addPlugin(syncPlugin({ channelName: 'my-app' }))
-```
 
-```tsx
-const store = gstate({ firstName: 'John', lastName: 'Doe' })
-store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)
-
-const [fullName] = store('fullName') // "John Doe"
+// Change in Tab 1 → Instantly updates Tab 2, Tab 3, etc.
+// ZERO server calls. Pure browser magic.
 ```
 
-### Error Handling with onError
-
-Handle errors gracefully with the `onError` callback - perfect for production apps:
+### Cloud Sync - Your Data, Everywhere
 
 ```tsx
-const store = gstate({ data: null }, {
-  onError: (error, context) => {
-    console.error(`Error in ${context.operation}:`, error.message)
-    // Send to error tracking service (Sentry, etc.)
-  }
-})
-```
+import { cloudSyncPlugin, createMongoAdapter } from '@biglogic/rgs/advanced'
 
-### Size Limits (maxObjectSize & maxTotalSize)
+const adapter = createMongoAdapter(
+  'https://data.mongodb-api.com/...',
+  'your-api-key'
+)
 
-Protect your app from memory issues with automatic size warnings:
+const store = gstate({ todos: [] })
+store._addPlugin(cloudSyncPlugin({
+  adapter,
+  autoSyncInterval: 30000  // Every 30 seconds
+}))
 
-```tsx
-const store = gstate({ data: {} }, {
-  // Warn if single value exceeds 5MB (Default is 0/Disabled for performance)
-  maxObjectSize: 5 * 1024 * 1024,
-  // Warn if total store exceeds 50MB (Default is 0/Disabled)
-  maxTotalSize: 50 * 1024 * 1024
-})
+// Manual sync when needed
+await store.plugins.cloudSync.sync()
 ```
 
-### Local-First Sync (Offline-by-Default)
+---
+
+## ☁️ Local-First Sync - Offline by Default
 
-RGS now includes a powerful Local-First Sync Engine that makes your app work offline by default:
+The **killer feature** that makes RGS unique:
 
 ```tsx
 import { gstate, useSyncedState } from '@biglogic/rgs'
 
-// Create store with built-in sync
+// Create store with automatic offline-first sync
 const store = gstate({
   todos: [],
   user: null
@@ -279,192 +288,196 @@ const store = gstate({
   namespace: 'myapp',
   sync: {
     endpoint: 'https://api.example.com/sync',
-    // Use a getter function to avoid exposing token in memory
     authToken: () => localStorage.getItem('auth_token'),
-    autoSyncInterval: 30000,  // Sync every 30s
-    syncOnReconnect: true,   // Auto-sync when back online
-    strategy: 'last-write-wins'  // Conflict resolution
+    autoSyncInterval: 30000,
+    syncOnReconnect: true,
+    strategy: 'last-write-wins'
   }
 })
 
-// Use in React - automatically synced!
+// Works offline. Automatically syncs when online.
 function TodoList() {
   const [todos, setTodos] = useSyncedState('todos')
 
-  // Works offline automatically
   const addTodo = (text) => {
     setTodos([...todos, { id: Date.now(), text }])
+    // Synced automatically! ✨
   }
 
-  return <div>{/* ... */}</div>
+  return <ul>{todos.map(t => <li>{t.text}</li>)}</ul>
 }
 ```
 
 ---
 
-## Multiple Stores
+## ⚡ Advanced Superpowers
 
-You can create multiple independent stores using namespaces:
+### Computed Values (Derived State)
 
 ```tsx
-// Option 1: gstate with namespace
-const userStore = gstate({ name: 'John' }, { namespace: 'users' })
-const appStore = gstate({ theme: 'dark' }, { namespace: 'app' })
+const store = gstate({
+  firstName: 'John',
+  lastName: 'Doe'
+})
 
-// In components - same key, different stores
-const [name] = userStore('name')     // 'John'
-const [theme] = appStore('theme')    // 'dark'
+// Auto-calculated derived state
+store.compute('fullName', (get) => `${get('firstName')} ${get('lastName')}`)
 
-// Option 2: initState + useStore (global default store)
-initState({ namespace: 'global' })
-const [value, setValue] = useStore('key')
+const fullName = store.get('fullName') // "John Doe"
 ```
 
-**Tip**: Keys are unique per-namespace, so you can use the same key name in different stores.
+### Error Handling
 
-## 🚀 Advanced Superpowers
+```tsx
+const store = gstate({ data: null }, {
+  onError: (error, context) => {
+    console.error(`Error in ${context.operation}:`, error.message)
+    // Send to Sentry, Datadog, etc.
+  }
+})
+```
 
-### 🔌 Official Plugin Ecosystem
+### Size Limits (Memory Protection)
 
-Extend the core functionality dynamically with specialized modules.
+```tsx
+const store = gstate({ data: {} }, {
+  maxObjectSize: 5 * 1024 * 1024,  // Warn if single value > 5MB
+  maxTotalSize: 50 * 1024 * 1024    // Warn if total > 50MB
+})
+```
 
-1. **ImmerPlugin**: Adds `setWithProduce` for functional updates.
-2. **UndoRedoPlugin**: Multi-level history management.
-3. **PersistencePlugin**: Advanced storage with custom serialization.
-4. **SyncPlugin**: Cross-tab state synchronization via BroadcastChannel.
-5. **SchemaPlugin**: Runtime validation (perfect for Zod).
-6. **DevToolsPlugin**: Redux DevTools integration.
-7. **TTLPlugin**: Time-to-live management.
-8. **AnalyticsPlugin**: Tracking bridge for metrics.
-9. **SnapshotPlugin**: Manual state checkpointing.
-10. **GuardPlugin**: Data transformation layer.
-11. **Local-First Sync**: Built-in offline-first with auto-sync (NEW!)
+---
 
-```typescript
-import { createStore, PersistencePlugin, undoRedoPlugin } from '@biglogic/rgs'
+## 📦 Build Sizes - Choose Your Weapon
 
-const store = createStore()
-store._addPlugin(PersistencePlugin({ storage: 'localStorage' }))
-store._addPlugin(undoRedoPlugin({ limit: 50 }))
+### Minimal Version (~0.16 KB)
+For embedded systems, widgets, IoT:
 
-// Undo like a pro
-store.undo()
-```
+```javascript
+import { createStore } from '@biglogic/rgs/core/minimal'
 
-### 🔬 Power Tools (Import from `rgs/advanced`)
+const store = createStore({ count: 0 })
+store.get('count')        // → 0
+store.set('count', 5)     // → true
+```
 
-Need the heavy artillery? We've got you covered.
+### Full Version (~32 KB)
+For production React apps with all features:
 
-- `createAsyncStore(fetcher)`: Atomic async state management.
-- `StorageAdapters`: High-level interfaces for any storage engine.
-- `Middleware / IPlugin`: Build your own extensions.
+```javascript
+import { gstate, createStore } from '@biglogic/rgs'
 
----
+const useCounter = gstate({ count: 0 })
+const count = useCounter(s => s.count)
+```
 
-## 🛡️ Quality & Testing
+| Version | Size | Use Case |
+|---------|------|----------|
+| **Minimal** | 0.16 KB | Embedded, IoT, Widgets |
+| **Full** | ~32 KB | React Apps, Enterprise |
 
-RGS is built with an obsession for reliability. Our test suite covers multiple layers to ensure zero-regressions:
+---
 
-- **Unit Tests (Jest)**: 100+ tests covering core logic, stores, and hooks.
-- **E2E Tests (Playwright)**: Real-world browser testing for cross-tab synchronization and Web Crypto API.
-- **Concurrency Testing**: Verification of race conditions in multi-tab environments.
+## 🧪 Testing - Rock-Solid Reliability
 
 ```bash
 # Run unit tests
 npm run test
 
-# Run E2E tests
+# Run E2E tests (Playwright)
 npm run test:e2e
 ```
 
----
-
-## 📦 Ultra-Minimal Build (< 2KB)
-
-RGS provides an **ultra-minimal** version for projects where bundle size is critical. This version includes only the core state management functionality.
-
-> [!WARNING]
-> ⚠️ **Not indicated for security and enterprise-level applications.**
-> For production apps requiring AES-256 encryption, RBAC, GDPR compliance, or audit logging, use the full version.
+- ✅ **100+ Unit Tests** (Jest) - Core logic, stores, hooks
+- ✅ **E2E Tests** (Playwright) - Real browser, cross-tab sync
+- ✅ **Concurrency Testing** - Race condition verification
+- ✅ **Security Tests** - AES-256, RBAC, GDPR
 
 ---
 
-### What's Included
+## 🏗️ Architecture
 
-- `createStore()` - Create a reactive store
-- `get(key)` - Read values
-- `set(key, value)` - Update values with automatic immutability
-- `subscribe(listener)` - Subscribe to changes
+```mermaid
+graph TB
+    subgraph API
+        A[gstate] --> D[IStore]
+        B[useStore] --> D
+        C[createStore] --> D
+    end
 
-### What's NOT Included (Full Features)
+    D --> E[Storage Adapter]
+    D --> F[Immer Proxy]
+    D --> G[Plugins]
+    D --> H[Security]
+    D --> I[Async Store]
 
-- ❌ Persistence (localStorage, etc.)
-- ❌ Security (RBAC, encryption)
-- ❌ Sync/Cloud features
-- ❌ Plugin system
-- ❌ Immer integration
-- ❌ Computed values
-- ❌ React hooks
+    E --> J[local]
+    E --> K[session]
+    E --> L[memory]
 
-### How to Use
+    G --> M[UndoRedo]
+    G --> N[Sync]
+    G --> O[Schema]
+    G --> P[Analytics]
+```
 
-#### Minimal Version (~0.16 KB)
+### Core Components
 
-For maximum performance and minimum bundle size:
+| Component | Description |
+|-----------|-------------|
+| **gstate()** | Creates store + hook in one line |
+| **useStore()** | React hook for subscribing to state |
+| **createStore()** | Classic store factory |
+| **IStore** | Core interface with get/set/subscribe |
+| **StorageAdapters** | local, session, memory persistence |
+| **Plugins** | Immer, Undo/Redo, Sync, Schema, etc. |
+| **Security** | Encryption, RBAC, GDPR consent |
 
-```javascript
-// Import minimal version
-import { createStore } from '@biglogic/rgs/core/minimal'
+---
 
-const store = createStore({ count: 0 })
+## 📚 Documentation
 
-// Basic operations
-store.get('count')        // → 0
-store.set('count', 5)    // → true
-store.subscribe(() => console.log('changed!'))
-```
+- [Getting Started](docs/chapters/02-getting-started.md)
+- [Plugin SDK](docs/chapters/05-plugin-sdk.md)
+- [Security Architecture](docs/chapters/09-security-architecture.md)
+- [Migration Guide](docs/chapters/08-migration-guide.md)
+- [API Reference](docs/api.md)
 
-#### Full Version (~32 KB)
+---
 
-For production apps with all features:
+## 🤝 Contributing
 
-```javascript
-// Import full version (default)
-import { gstate, createStore } from '@biglogic/rgs'
+Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) first.
 
-// Zen way - creates hook + store
-const useCounter = gstate({ count: 0 })
-const count = useCounter(s => s.count)
+```bash
+# Clone and setup
+git clone https://github.com/BigLogic-ca/rgs.git
+cd rgs
+npm install
 
-// Classic way
-const store = createStore({ count: 0 })
-store.set('count', 5, { persist: true })
-store._addPlugin(undoRedoPlugin())
+# Run tests
+npm run test
 ```
 
-### When to Use What?
+---
 
-| Scenario | Use | Size |
-|----------|-----|------|
-| Embedded/IoT | Minimal | 0.16 KB |
-| Widgets/Badges | Minimal | 0.16 KB |
-| React Apps | Full | ~32 KB |
-| Enterprise | Full | ~32 KB |
+## 📄 License
 
-### Size Comparison
-
-| Version | Size | Use Case |
-|---------|------|----------|
-| **Minimal** | 0.16 KB | Embedded systems, tiny apps |
-| **Full** | ~32 KB | Production apps |
+**MIT** © [Dario Passariello](https://github.com/passariello)
 
 ---
 
-## 📄 License
+<div align="center">
 
-MIT © [Dario Passariello](https://github.com/passariello)
+## 🔥 Built for Those Who Demand **Excellence**
 
----
+[![Powered by Immer](https://img.shields.io/badge/Powered%20by-Immer-2ECC71.svg)](https://github.com/immerjs/immer)
+[![Typed with TypeScript](https://img.shields.io/badge/Typed%20with-TypeScript-3178C6.svg)](https://www.typescriptlang.org/)
+[![Tested with Jest](https://img.shields.io/badge/Tested%20with-Jest-C21325.svg)](https://jestjs.io/)
+[![E2E with Playwright](https://img.shields.io/badge/E2E%20with-Playwright-2ECC71.svg)](https://playwright.dev/)
+
+**Made with ❤️ and a lot of caffè espresso!**
+
+[⬆ Back to top](#-argis-rgs---reactive-global-state)
 
-**Designed for those who build the future.**
-Made with ❤️ and a lot of caffe' espresso!
+</div>