strata-storage 2.4.2 → 2.5.0

package/README.md

@@ -1,269 +1,517 @@
 # Strata Storage
 
-> Zero-dependency universal storage plugin providing a unified API for all storage operations across web, Android, and iOS platforms.
+> Zero-dependency universal storage for the web, iOS, and Android. One API for `localStorage`, IndexedDB, cookies, the URL, native Keychain/Keystore, SQLite, and more — with optional React, Vue, Angular, Capacitor, and Firebase surfaces.
+
+- **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** — quick reference for AI development agents (Claude Code, Cursor, Copilot).
 
 [![npm version](https://img.shields.io/npm/v/strata-storage.svg)](https://www.npmjs.com/package/strata-storage)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9+-blue.svg)](https://www.typescriptlang.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
 [![Platform](https://img.shields.io/badge/platform-Web%20%7C%20iOS%20%7C%20Android-lightgrey.svg)](https://github.com/aoneahsan/strata-storage)
 
-## Features
+- **Version:** `2.5.0`
+- **License:** Apache-2.0
+- **Node.js:** `>= 24.13.0`
+- **Module format:** ESM only
 
-- **🚀 Zero Dependencies** - No external runtime dependencies, pure TypeScript implementation
-- **🌐 Universal API** - Single consistent API across web, iOS, and Android
-- **🔒 Built-in Encryption** - Secure data storage using native crypto APIs
-- **📦 Compression** - Automatic data compression for large objects
-- **⏱️ TTL Support** - Automatic expiration with time-to-live
-- **🔄 Cross-Tab Sync** - Real-time synchronization across browser tabs
-- **🎯 Advanced Queries** - Tag-based querying and filtering
-- **📱 Mobile Ready** - Native iOS and Android storage with Capacitor
-- **💾 Multiple Adapters** - localStorage, IndexedDB, SQLite, Keychain, and more
-- **🎨 Framework Integrations** - React hooks, Vue composables, Angular services
+## Why Strata Storage
 
-## Installation
+Every product re-solves the same storage problem: pick a backend per platform, learn its quirks, wrap it for your framework, and bolt on encryption, expiry, and cross-tab sync by hand. Strata Storage replaces that with one adapter-based API that runs everywhere and keeps the runtime package free of dependencies.
 
-```bash
-npm install strata-storage
-```
+- **Zero runtime dependencies.** The core is pure TypeScript. React, Vue, Angular, and `@capacitor/core` are optional peer dependencies — install only what you use.
+- **One API, every backend.** `get`/`set`/`remove`/`query`/`subscribe` behave the same whether the value lives in `localStorage`, IndexedDB, the URL, or the iOS Keychain.
+- **Provider-free.** `defineStorage()` returns a ready-to-use instance you create once and import anywhere — no React context, Vue plugin, or Angular module required (the Provider/Plugin/Module styles still work if you prefer them).
+- **Opt-in power features.** Encryption, compression, TTL, queries, cross-tab sync, integrity checksums, durable writes, mirroring, and snapshots are all off by default and added per call or per instance.
 
-Or using yarn:
+## Installation
 
 ```bash
 yarn add strata-storage
 ```
 
-Or using pnpm:
+Framework adapters import from sub-paths; no extra install beyond the framework itself:
 
 ```bash
-pnpm add strata-storage
+# React / Vue / Angular peers are optional — install the one you use
+yarn add react        # for strata-storage/react
+yarn add vue          # for strata-storage/vue
+yarn add @angular/core @angular/forms   # for strata-storage/angular
+yarn add @capacitor/core                # for strata-storage/capacitor
 ```
 
 ## Quick Start
 
-### Basic Usage
+The shortest path is the default `storage` instance. It registers the standard web adapters and initializes lazily on first use, so importing the package does no I/O.
 
 ```typescript
-import { Strata } from 'strata-storage';
-
-// Create and initialize storage
-const storage = new Strata();
-await storage.initialize();
-
-// Store data
-await storage.set('username', 'john_doe');
-await storage.set('user', {
-  id: 123,
-  name: 'John Doe',
-  email: 'john@example.com'
+import { storage } from 'strata-storage';
+
+// No setup, no Provider, no initialize() call — works immediately.
+await storage.set('user', { id: 123, name: 'John Doe' });
+const user = await storage.get<{ id: number; name: string }>('user');
+
+await storage.remove('user');
+await storage.clear();
+```
+
+Need your own configured instance? Use `defineStorage()` — it is the same factory the default instance is built from.
+
+```typescript
+import { defineStorage } from 'strata-storage';
+
+export const storage = defineStorage({
+  defaultStorages: ['indexedDB', 'localStorage'],
+  encryption: { enabled: true, password: process.env.STORAGE_KEY! },
 });
 
-// Retrieve data
-const username = await storage.get('username');
-const user = await storage.get('user');
+await storage.set('token', '...', { encrypt: true });
+```
 
-// Remove data
-await storage.remove('username');
+`defineStorage()` registers memory, `localStorage`, `sessionStorage`, IndexedDB, cookies, and the Cache API. Add the URL adapter or native adapters yourself when you need them (see below).
 
-// Clear all data
-await storage.clear();
+## Provider-Free Usage
+
+The recommended pattern across all frameworks: create one instance and bind to it. No Provider, plugin, or module is required. The Provider-based styles remain available and are documented in [docs/examples/frameworks](./docs/examples/frameworks).
+
+### Vanilla JavaScript / TypeScript
+
+```typescript
+import { defineStorage } from 'strata-storage';
+
+export const storage = defineStorage();
+
+await storage.set('theme', 'dark');
+const theme = await storage.get<string>('theme');
+```
+
+### React
+
+Bind the hooks to an instance once at module scope with `createStrataHooks`, then use them in any component — no `<StrataProvider>` needed.
+
+```tsx
+// storage.ts
+import { defineStorage } from 'strata-storage';
+import { createStrataHooks } from 'strata-storage/react';
+
+export const storage = defineStorage();
+export const { useStorage, useStorageQuery, useStorageTTL } = createStrataHooks(storage);
+```
+
+```tsx
+// Settings.tsx
+import { useStorage } from './storage';
+
+function Settings() {
+  // [value, setValue, loading]
+  const [theme, setTheme, loading] = useStorage<string>('theme', 'light');
+
+  if (loading) return <p>Loading…</p>;
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Theme: {theme}
+    </button>
+  );
+}
+```
+
+Prefer context? `<StrataProvider>` still works and now accepts an `instance` prop so it can wrap an instance you created yourself:
+
+```tsx
+import { StrataProvider, useStorage } from 'strata-storage/react';
+import { storage } from './storage';
+
+<StrataProvider instance={storage}>
+  <App />
+</StrataProvider>;
 ```
 
-### Advanced Features
+### Vue
 
-#### Encryption
+`createStrataComposables` binds the composables to an instance. Each built-in composable also accepts an optional instance as its last argument, and the classic `StrataPlugin` still works.
 
 ```typescript
-const storage = new Strata({
-  encryption: {
-    enabled: true,
-    password: 'your-secure-password'
-  }
-});
+// storage.ts
+import { defineStorage } from 'strata-storage';
+import { createStrataComposables } from 'strata-storage/vue';
+
+export const storage = defineStorage();
+export const { useStorage, useStorageQuery, useStorageTTL } = createStrataComposables(storage);
+```
+
+```vue
+<script setup lang="ts">
+import { useStorage } from './storage';
+
+const { value: theme, update } = useStorage<string>('theme', 'light');
+</script>
 
-await storage.initialize();
-await storage.set('sensitiveData', { token: 'secret' });
+<template>
+  <button @click="update(theme === 'light' ? 'dark' : 'light')">Theme: {{ theme }}</button>
+</template>
 ```
 
-#### Time-To-Live (TTL)
+### Angular
+
+`provideStrata` accepts either a pre-created instance or a config object, and registers `StrataService` for injection. It works in `bootstrapApplication` (standalone) or a component's `providers`. The `STRATA_INSTANCE` token holds the instance; `StrataModule.forRoot(config)` remains for NgModule apps.
 
 ```typescript
-// Data expires in 1 hour
-await storage.set('sessionData', data, {
-  ttl: 60 * 60 * 1000
+// main.ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { defineStorage } from 'strata-storage';
+import { provideStrata } from 'strata-storage/angular';
+import { AppComponent } from './app/app.component';
+
+const storage = defineStorage();
+
+bootstrapApplication(AppComponent, {
+  providers: [provideStrata(storage)], // or provideStrata({ defaultStorages: ['indexedDB'] })
 });
 ```
 
-#### Compression
-
 ```typescript
-const storage = new Strata({
-  compression: {
-    enabled: true,
-    threshold: 1024 // Compress data larger than 1KB
+// any.component.ts
+import { Component } from '@angular/core';
+import { StrataService } from 'strata-storage/angular';
+
+@Component({ /* ... */ })
+export class AnyComponent {
+  constructor(private storage: StrataService) {}
+
+  save() {
+    // StrataService methods return RxJS Observables
+    this.storage.set('theme', 'dark').subscribe();
   }
-});
+}
+```
+
+## Synchronous API
+
+For UI code that must read or write without `await` — initial render, event handlers, synchronous state hydration — Strata exposes a synchronous API alongside the async one:
+
+```typescript
+import { defineStorage } from 'strata-storage';
+
+const storage = defineStorage();
 
-await storage.initialize();
-await storage.set('largeData', bigObject);
+storage.setSync('lastTab', 'inbox');
+const tab = storage.getSync<string>('lastTab'); // 'inbox'
+storage.hasSync('lastTab');                      // true
+storage.keysSync();                              // string[]
+storage.removeSync('lastTab');
+storage.clearSync();
 ```
 
-#### Cross-Tab Sync
+### Limitations (read these)
+
+The sync API only works on adapters that are genuinely synchronous: **`memory`, `localStorage`, `sessionStorage`, `cookies`, and `url`**. It does not paper over async backends, and it cannot do work that is inherently asynchronous:
+
+- Targeting an async-only adapter (`indexedDB`, `cache`, `sqlite`, `filesystem`, `secure`, `preferences`) throws a `StorageError` telling you to use the async API.
+- `setSync` with `{ encrypt: true }` or `{ compress: true }` throws — Web Crypto and compression are async, so use `await storage.set(...)`.
+- `getSync` on a value that was stored encrypted or compressed throws — read it with `await storage.get(...)`.
+
+TTL, tags, and metadata work with the sync API; encryption and compression do not.
 
 ```typescript
-const storage = new Strata({
-  sync: { enabled: true }
-});
+// Pick a sync-capable backend explicitly when needed:
+storage.setSync('filters', { status: 'open' }, { storage: 'localStorage', ttl: 60_000 });
+```
+
+## URL Adapter
 
-await storage.initialize();
+The `URLAdapter` (storage type `'url'`) persists state in the page URL so it survives reloads and round-trips through shareable/bookmarkable links — filters, the active tab, pagination, and other small UI state. It is inherently synchronous and emits change events on `popstate`/`hashchange`, so back/forward navigation and manual URL edits notify subscribers.
+
+```typescript
+import { defineStorage, URLAdapter } from 'strata-storage';
 
-// Subscribe to changes from other tabs
+const storage = defineStorage();
+storage.registerAdapter(new URLAdapter());
+
+// Write to the URL (no await needed — URL access is synchronous)
+storage.setSync('tab', 'pending', { storage: 'url' });
+storage.setSync('page', 3, { storage: 'url' });
+
+// Read it back (e.g. on reload)
+const tab = storage.getSync<string>('tab', { storage: 'url' });
+
+// React to back/forward navigation or manual edits
 storage.subscribe((change) => {
-  console.log(`Key ${change.key} changed to:`, change.newValue);
-});
+  if (change.key === 'tab') applyTab(change.newValue);
+}, { storage: 'url' });
 ```
 
-## Platform Support
+### Configuration
 
-### Web Browsers
-- **localStorage** - Simple key-value storage
-- **sessionStorage** - Session-scoped storage
-- **IndexedDB** - Large structured data
-- **Cookies** - Cookie-based storage
-- **Cache API** - HTTP cache storage
-- **Memory** - In-memory storage
+Pass `URLAdapterConfig` when constructing the adapter:
 
-### iOS (via Capacitor)
-- **UserDefaults** - User preferences
-- **Keychain** - Secure credential storage
-- **SQLite** - Database storage
-- **FileManager** - File-based storage
+```typescript
+new URLAdapter(); // defaults below
+```
 
-### Android (via Capacitor)
-- **SharedPreferences** - Simple key-value storage
-- **EncryptedSharedPreferences** - Secure storage
-- **SQLite** - Database storage
-- **File Storage** - File-based storage
+| Option | Type | Default | Meaning |
+|--------|------|---------|---------|
+| `mode` | `'query'` \| `'hash'` | `'query'` | Store params in the query string (`?strata.tab=...`) or the hash fragment (`#strata.tab=...`). |
+| `prefix` | `string` | `'strata.'` | Prefix on every param name to avoid collisions with your own query params. |
+| `history` | `'push'` \| `'replace'` | `'replace'` | Whether each write adds a browser history entry or replaces the current one. |
+| `maxLength` | `number` | `2000` | Soft warning threshold (chars) for total URL length. |
 
-## Framework Integrations
+The adapter is configured through `StrataConfig.adapters.url` when you let Strata manage it:
 
-### React
+```typescript
+const storage = defineStorage({ adapters: { url: { mode: 'hash', history: 'push' } } });
+storage.registerAdapter(new URLAdapter());
+```
+
+### Limitations (read these)
+
+- **Length limits.** URLs have practical limits (~2000 chars in some browsers and servers). This adapter is for small, simple, serializable state — not bulk data. Writes past `maxLength` are allowed but logged as a warning.
+- **Server visibility.** In `'query'` mode the data is sent to the server on every navigation and appears in server/proxy logs. Use `'hash'` mode to keep it client-only (the fragment is never sent to the server).
+- **Browser only.** Outside a browser (SSR/Node) the adapter reports unavailable; `isAvailable()` returns `false`.
+- **Not persistent.** State lives only as long as the URL does — it is not durable storage.
+
+## Disaster Recovery
+
+Strata includes opt-in recovery features for data you cannot afford to silently lose. **Everything here is off by default** — enable only what you need, since each adds overhead.
+
+### Integrity checksums
+
+Set `integrity: true` (or per call `{ verify: true }`) to compute and store an FNV-1a checksum with each value and verify it on read. On corruption, Strata first attempts mirror read-repair (below); otherwise it honors `{ ignoreCorruption: true }` (returns `null`) or throws a typed `IntegrityError`.
 
 ```typescript
-import { useStrata } from 'strata-storage/react';
+import { defineStorage } from 'strata-storage';
 
-function MyComponent() {
-  const { data, loading, set, remove } = useStrata('myKey');
+const storage = defineStorage({ integrity: true });
 
-  return (
-    <div>
-      <p>{data}</p>
-      <button onClick={() => set('newValue')}>Update</button>
-    </div>
-  );
-}
+await storage.set('config', settings);   // checksum stored
+const config = await storage.get('config'); // verified; throws IntegrityError if corrupted
 ```
 
-### Vue
+> **Honest note:** checksums are **FNV-1a, non-cryptographic**. They cheaply detect *accidental* corruption (truncated writes, bit flips, partial storage). They do **not** resist tampering — for tamper resistance use the encryption feature.
+
+### Durable writes
+
+`durableWrites: true` (or per call `{ durable: true }`) reads each value back after writing and retries on mismatch, throwing `StorageError` if it cannot confirm the write after a few attempts. This adds one read per write.
 
 ```typescript
-import { useStrata } from 'strata-storage/vue';
+const storage = defineStorage({ durableWrites: true });
+await storage.set('order', order); // confirmed written, or throws
+```
 
-export default {
-  setup() {
-    const { data, loading, set, remove } = useStrata('myKey');
+### Mirroring (read-repair)
 
-    return { data, loading, set, remove };
-  }
-};
+`mirror: [...]` copies every write/remove to backup storage types. On a primary read miss or corruption, Strata recovers the value from a mirror and repairs the primary in place.
+
+```typescript
+const storage = defineStorage({
+  defaultStorages: ['localStorage'],
+  integrity: true,
+  mirror: ['indexedDB'], // localStorage is primary; indexedDB backs it up
+});
 ```
 
-### Angular
+### Snapshots and scheduled backups
+
+`snapshot()` produces a portable, integrity-verified backup string (embedding a checksum manifest); `restore()` validates that checksum and throws `IntegrityError` on a corrupted backup. `autoBackup` schedules periodic snapshots to a durable adapter.
 
 ```typescript
-import { StrataService } from 'strata-storage/angular';
+const backup = await storage.snapshot();      // store/download this string
+await storage.restore(backup);                 // validates, then restores
 
-@Component({ /* ... */ })
-export class MyComponent {
-  constructor(private storage: StrataService) {}
+// Scheduled, every 5 minutes, into indexedDB
+const storage = defineStorage({
+  autoBackup: { interval: 5 * 60_000, storage: 'indexedDB' },
+});
+```
 
-  async saveData() {
-    await this.storage.set('key', 'value');
-  }
-}
+Integrity helpers and error classes are exported for direct use:
+
+```typescript
+import { computeChecksum, verifyChecksum, IntegrityError } from 'strata-storage';
 ```
 
-## Documentation
+## Advanced Features
 
-- **[Getting Started](docs/getting-started/installation.md)** - Installation and setup guide
-- **[Quick Start](docs/getting-started/quick-start.md)** - Get up and running in minutes
-- **[API Reference](docs/api/README.md)** - Complete API documentation
-- **[Platform Guides](docs/guides/platforms/web.md)** - Platform-specific information
-- **[Examples](docs/examples/README.md)** - Real-world usage examples
-- **[Migration Guide](docs/MIGRATION.md)** - Migrating from other storage solutions
-
-## Storage Adapters
-
-| Adapter | Platform | Use Case |
-|---------|----------|----------|
-| `localStorage` | Web | Simple key-value, persistent |
-| `sessionStorage` | Web | Session-scoped data |
-| `indexedDB` | Web | Large structured data |
-| `cookies` | Web | Cookie-based storage |
-| `cache` | Web | HTTP cache |
-| `memory` | All | Temporary in-memory |
-| `preferences` | Mobile | User preferences (UserDefaults/SharedPreferences) |
-| `secure` | Mobile | Encrypted storage (Keychain/EncryptedSharedPreferences) |
-| `sqlite` | Mobile | Database storage |
-| `filesystem` | Mobile | File-based storage |
+### Encryption (async only)
 
-## Requirements
+```typescript
+const storage = defineStorage({ encryption: { enabled: true, password: 'secret' } });
+await storage.set('secret', { token: 'abc' });        // encrypted with AES-GCM
+await storage.set('one-off', data, { encrypt: true }); // per-call override
+```
 
-- **Node.js**: 18.0.0 or higher
-- **TypeScript**: 5.0+ (optional, but recommended)
-- **Capacitor**: 5.x or 6.x (for mobile platforms)
+### TTL / expiration
 
-## Browser Support
+```typescript
+await storage.set('session', data, { ttl: 3_600_000 });          // expires in 1 hour
+await storage.set('cache', data, { ttl: 600_000, sliding: true }); // reset on access
+const ms = await storage.getTTL('session');
+await storage.persist('session');                                  // remove expiry
+```
+
+### Compression (async only)
+
+```typescript
+const storage = defineStorage({ compression: { enabled: true, threshold: 1024 } });
+await storage.set('largePayload', bigObject); // compressed above 1KB
+```
+
+### Cross-tab sync
+
+```typescript
+const storage = defineStorage({ sync: { enabled: true } });
+storage.subscribe((change) => {
+  console.log(`${change.key} changed`, change.newValue);
+});
+```
+
+### Queries
+
+```typescript
+await storage.set('user:1', user, { tags: ['users', 'active'] });
+const active = await storage.query({
+  tags: { $in: ['active'] },
+  'value.age': { $gte: 18 },
+});
+```
+
+## Platform Support
 
-- Chrome/Edge: Latest 2 versions
-- Firefox: Latest 2 versions
-- Safari: Latest 2 versions
-- iOS Safari: iOS 13+
-- Android WebView: Android 8+
+### Web (works in any JS environment)
 
-## Why Strata Storage?
+| Adapter | Backend | Use case |
+|---------|---------|----------|
+| `memory` | In-memory `Map` | Always-available fallback, tests |
+| `localStorage` | `window.localStorage` | Persistent key-value (~5 MB) |
+| `sessionStorage` | `window.sessionStorage` | Session-scoped data |
+| `indexedDB` | IndexedDB | Large structured data |
+| `cookies` | `document.cookie` | Small, server-accessible data |
+| `cache` | Cache API | Service-worker / HTTP cache |
+| `url` | `location` query/hash | Shareable UI state (see above) |
 
-### Zero Dependencies
-Unlike other storage solutions that depend on multiple packages, Strata Storage has **zero runtime dependencies**. Everything is built from scratch, ensuring:
-- Smaller bundle size
-- No dependency conflicts
-- Better security
-- Full control over implementation
+### iOS and Android (via Capacitor)
 
-### Universal API
-One API works everywhere. No need to learn different APIs for web and mobile, or switch between libraries:
+Register native adapters yourself when running under Capacitor:
 
 ```typescript
-// Same code works on web, iOS, and Android
-await storage.set('key', 'value');
-const value = await storage.get('key');
+import { defineStorage } from 'strata-storage';
+import { PreferencesAdapter, SecureStorageAdapter } from 'strata-storage/capacitor';
+
+const storage = defineStorage();
+storage.registerAdapter(new PreferencesAdapter());  // UserDefaults / SharedPreferences
+storage.registerAdapter(new SecureStorageAdapter()); // Keychain / EncryptedSharedPreferences
+
+await storage.set('secret', token, { storage: 'secure' });
+```
+
+| Adapter | iOS backend | Android backend |
+|---------|-------------|-----------------|
+| `preferences` | UserDefaults | SharedPreferences |
+| `secure` | Keychain | EncryptedSharedPreferences |
+| `sqlite` | SQLite | SQLite |
+| `filesystem` | FileManager | Filesystem |
+
+> **Honest note:** the native iOS/Android adapters depend on your downstream Capacitor project setup and platform configuration. Behavior on a real device should be verified on-device — native storage cannot be exercised by the web/Node test suite.
+
+### Firebase (optional cloud sync)
+
+```typescript
+import { defineStorage } from 'strata-storage';
+import { enableFirebaseSync } from 'strata-storage/firebase';
+
+const storage = defineStorage();
+await enableFirebaseSync(storage, { apiKey: '…', projectId: '…', firestore: true });
+await storage.set('data', value, { storage: 'firestore' });
 ```
 
-### Built-in Features
-Advanced features included out of the box:
-- Encryption (Web Crypto API / Native Crypto)
-- Compression (LZ-string algorithm)
-- TTL/Expiration
-- Cross-tab sync
-- Advanced queries
-- Data migrations
+## Storage Types
+
+| Type | Platform | Synchronous | Encrypt/Compress | Notes |
+|------|----------|-------------|-------------------|-------|
+| `memory` | All | ✅ | async only | Always available |
+| `localStorage` | Web | ✅ | async only | ~5 MB, persistent |
+| `sessionStorage` | Web | ✅ | async only | Session-scoped |
+| `indexedDB` | Web | ❌ | async only | Large structured data |
+| `cookies` | Web | ✅ | async only | ~4 KB, server-readable |
+| `cache` | Web | ❌ | async only | Cache API |
+| `url` | Web | ✅ | async only | Shareable UI state, length-limited |
+| `preferences` | Mobile | ❌ | async only | UserDefaults / SharedPreferences |
+| `secure` | Mobile | ❌ | async only | Keychain / EncryptedSharedPreferences |
+| `sqlite` | Mobile | ❌ | async only | Native SQLite |
+| `filesystem` | Mobile | ❌ | async only | Native files |
+
+"async only" means encryption and compression require the `await storage.set(...)` path — the synchronous API cannot encrypt or compress.
+
+## Requirements
+
+- **Node.js:** `>= 24.13.0`
+- **TypeScript:** strict mode supported (optional, recommended)
+- **Capacitor:** `@capacitor/core >= 8.0.0` (for native platforms; optional peer dependency)
+
+Optional peer dependencies (install only the ones you use): `react >= 19.2.3`, `vue >= 3.5.26`, `@angular/core` & `@angular/forms >= 21.0.6`.
+
+## Documentation
+
+### Getting Started
+- [Installation](./docs/getting-started/installation.md) — install and set up
+- [Quick Start](./docs/getting-started/quick-start.md) — running in minutes
+- [Configuration](./docs/getting-started/configuration.md) — configuration options
+
+### Core
+- [API Reference](./docs/api/README.md) — complete API
+- [Core API (`Strata`)](./docs/api/core/strata.md) — the main class
+- [Type Definitions](./docs/api/core/types.md) — TypeScript types
+- [Error Handling](./docs/api/core/errors.md) — error classes
+
+### Storage Adapters
+- [Web Adapters](./docs/api/adapters/README.md#web-adapters)
+  - [localStorage](./docs/api/adapters/web/localstorage.md)
+  - [sessionStorage](./docs/api/adapters/web/sessionstorage.md)
+  - [IndexedDB](./docs/api/adapters/web/indexeddb.md)
+  - [Cookies](./docs/api/adapters/web/cookies.md)
+  - [Cache API](./docs/api/adapters/web/cache.md)
+  - [Memory](./docs/api/adapters/web/memory.md)
+  - [URL](./docs/api/adapters/web/url.md)
+- [Capacitor Adapters](./docs/api/adapters/README.md#capacitor-adapters)
+  - [Preferences](./docs/api/adapters/capacitor/preferences.md)
+  - [Secure Storage](./docs/api/adapters/capacitor/secure.md)
+  - [SQLite](./docs/api/adapters/capacitor/sqlite.md)
+  - [Filesystem](./docs/api/adapters/capacitor/filesystem.md)
+
+### Features
+- [Encryption](./docs/guides/features/encryption.md)
+- [Compression](./docs/guides/features/compression.md)
+- [TTL Management](./docs/api/features/ttl.md)
+- [Cross-Tab Sync](./docs/guides/features/sync.md)
+- [Query Engine](./docs/guides/features/queries.md)
+- [Migrations](./docs/guides/features/migrations.md)
+- [Recovery & Integrity](./docs/api/features/recovery.md)
+
+### Platform Guides
+- [Web](./docs/guides/platforms/web.md)
+- [iOS](./docs/guides/platforms/ios.md)
+- [Android](./docs/guides/platforms/android.md)
+- [Capacitor](./docs/guides/platforms/capacitor.md)
+
+### Examples
+- [Basic Usage](./docs/examples/basic-usage.md)
+- [React Integration](./docs/examples/frameworks/react.md)
+- [Vue Integration](./docs/examples/frameworks/vue.md)
+- [Angular Integration](./docs/examples/frameworks/angular.md)
+- [All Examples](./docs/examples/README.md)
+
+### Reference
+- [Changelog](./docs/reference/changelog.md)
+- [FAQ](./docs/reference/faq.md)
+- [Troubleshooting](./docs/reference/troubleshooting.md)
+- [Migration Guide](./docs/MIGRATION.md)
 
 ## Contributing
 
-Contributions are welcome! Please read the [Contributing Guide](CONTRIBUTING.md) for details.
+Contributions are welcome — please read the [Contributing Guide](./.github/CONTRIBUTING.md).
 
 ## License
 
-Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+Apache License 2.0 — see [LICENSE](LICENSE). Free for commercial use, modification, and distribution with patent protection; attribution required; provided without warranty.
 
 ## Author
 
@@ -277,19 +525,17 @@ Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
 
 ## Links
 
-- **NPM Package**: [npmjs.com/package/strata-storage](https://www.npmjs.com/package/strata-storage)
-- **GitHub Repository**: [github.com/aoneahsan/strata-storage](https://github.com/aoneahsan/strata-storage)
-- **Issue Tracker**: [github.com/aoneahsan/strata-storage/issues](https://github.com/aoneahsan/strata-storage/issues)
-- **Documentation**: [github.com/aoneahsan/strata-storage/tree/main/docs](https://github.com/aoneahsan/strata-storage/tree/main/docs)
+- **NPM Package:** [npmjs.com/package/strata-storage](https://www.npmjs.com/package/strata-storage)
+- **GitHub Repository:** [github.com/aoneahsan/strata-storage](https://github.com/aoneahsan/strata-storage)
+- **Issue Tracker:** [github.com/aoneahsan/strata-storage/issues](https://github.com/aoneahsan/strata-storage/issues)
+- **Documentation:** [github.com/aoneahsan/strata-storage/tree/main/docs](https://github.com/aoneahsan/strata-storage/tree/main/docs)
 
 ## Support
 
-If you encounter any issues or have questions:
-
-1. Check the [FAQ](docs/reference/faq.md)
+1. Check the [FAQ](./docs/reference/faq.md)
 2. Search [existing issues](https://github.com/aoneahsan/strata-storage/issues)
-3. Create a [new issue](https://github.com/aoneahsan/strata-storage/issues/new)
+3. Open a [new issue](https://github.com/aoneahsan/strata-storage/issues/new)
 
 ---
 
-Made with ❤️ by [Ahsan Mahmood](https://aoneahsan.com)
+Made by [Ahsan Mahmood](https://aoneahsan.com). **One API. Every Storage. Everywhere.**