@framers/sql-storage-adapter 0.1.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Framers
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Framers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.md

@@ -1,363 +1,241 @@
-# SQL Storage Adapter
-
-[![npm version](https://img.shields.io/npm/v/@framers/sql-storage-adapter.svg)](https://www.npmjs.com/package/@framers/sql-storage-adapter)
-[![CI](https://github.com/wearetheframers/sql-storage-adapter/actions/workflows/ci.yml/badge.svg)](https://github.com/wearetheframers/sql-storage-adapter/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/wearetheframers/sql-storage-adapter/branch/master/graph/badge.svg)](https://codecov.io/gh/wearetheframers/sql-storage-adapter)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
-
-> One SQL interface for Node.js, browsers, and mobile apps. Write your database code once, run it anywhere.
-
-**[Documentation](https://wearetheframers.github.io/sql-storage-adapter/)** | **[GitHub](https://github.com/wearetheframers/sql-storage-adapter)** | **[NPM](https://www.npmjs.com/package/@framers/sql-storage-adapter)**
-
-## Why?
-
-Build apps that work across platforms without rewriting database code:
-- 🖥️ **Desktop** (Electron) - fast local storage with better-sqlite3
-- 🌐 **Web** - in-browser SQL with sql.js (WebAssembly)
-- 📱 **Mobile** (Capacitor/React Native) - native SQLite
-- ☁️ **Server** - PostgreSQL or SQLite
-
-```typescript
-import { createDatabase } from '@framers/sql-storage-adapter';
-
-// Auto-picks the best adapter for your environment
-const db = await createDatabase();
-
-// Same code everywhere
-await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
-const user = await db.get('SELECT * FROM users WHERE id = ?', [1]);
-```
-
-## Installation
-
-```bash
-npm install @framers/sql-storage-adapter
-
-# Install adapters you need:
-npm install better-sqlite3      # Desktop (Node.js/Electron)
-npm install pg                  # PostgreSQL (servers)
-npm install @capacitor-community/sqlite  # Mobile (Capacitor)
-# sql.js included - no extra install needed
-```
-
-## Quick Start
-
-```typescript
-import { createDatabase } from '@framers/sql-storage-adapter';
-
-// Create database (auto-detects best option)
-const db = await createDatabase();
-
-// Create table
-await db.exec(`
-  CREATE TABLE IF NOT EXISTS todos (
-    id INTEGER PRIMARY KEY,
-    task TEXT NOT NULL,
-    done INTEGER DEFAULT 0
-  )
-`);
-
-// Insert data
-await db.run('INSERT INTO todos (task) VALUES (?)', ['Buy groceries']);
-
-// Query data
-const todos = await db.all('SELECT * FROM todos WHERE done = 0');
-
-// Clean up
-await db.close();
-```
-
-## Core API
-
-```typescript
-// Execute SQL (no results)
-await db.exec('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
-
-// Run mutation (INSERT/UPDATE/DELETE)
-const result = await db.run('INSERT INTO users (name) VALUES (?)', ['Alice']);
-console.log(result.lastInsertRowid);  // Auto-increment ID
-
-// Get single row
-const user = await db.get<User>('SELECT * FROM users WHERE id = ?', [1]);
-
-// Get all rows
-const users = await db.all<User>('SELECT * FROM users');
-
-// Transactions (automatic commit/rollback)
-await db.transaction(async (tx) => {
-  await tx.run('INSERT INTO users (name) VALUES (?)', ['Bob']);
-  await tx.run('INSERT INTO posts (user_id, title) VALUES (?, ?)', [1, 'Hello']);
-});
-
-// Batch operations (if supported)
-if (db.capabilities.has('batch')) {
-  await db.batch([
-    { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Alice'] },
-    { statement: 'INSERT INTO users (name) VALUES (?)', parameters: ['Bob'] }
-  ]);
-}
-
-// Close connection
-await db.close();
-```
-
-## Adapter Selection
-
-Auto-detection order:
-
-```
-🖥️ Node.js:     better-sqlite3 → sql.js
-🌐 Browser:     sql.js
-📱 Mobile:      capacitor-sqlite → sql.js
-☁️ Server:      postgres → better-sqlite3 → sql.js
-```
-
-Override with specific adapter:
-
-```typescript
-// Use PostgreSQL explicitly
-const db = await createDatabase({ 
-  url: 'postgresql://localhost/mydb' 
-});
-
-// Use SQLite explicitly
-const db = await createDatabase({ 
-  file: './app.db' 
-});
-
-// Custom priority
-const db = await createDatabase({
-  priority: ['postgres', 'better-sqlite3'],
-  postgres: { connectionString: process.env.DATABASE_URL },
-  filePath: './fallback.db'
-});
-```
-
-## Auto-Sync & Offline Support
-
-Build offline-first apps with automatic cloud sync:
-
-```typescript
-import { createSyncManager } from '@framers/sql-storage-adapter';
-
-const manager = await createSyncManager({
-  primary: './app.db',                     // Local SQLite
-  remote: process.env.DATABASE_URL,        // Cloud PostgreSQL
-  sync: {
-    mode: 'auto',                          // Auto-sync after writes
-    conflictStrategy: 'last-write-wins'
-  }
-});
-
-// Work offline
-await manager.db.run('INSERT INTO tasks (title) VALUES (?)', ['Buy milk']);
-
-// Sync manually when needed
-const result = await manager.sync();
-console.log(`Synced ${result.recordsSynced} records`);
-```
-
-**Sync Modes:**
-- `manual` - Call `sync()` explicitly (default)
-- `auto` - Syncs after writes (debounced)
-- `periodic` - Syncs every N seconds
-- `realtime` - Syncs immediately on every write
-- `on-reconnect` - Syncs when network returns
-
-**Conflict Strategies:**
-- `last-write-wins` - Newest timestamp wins (default)
-- `local-wins` - Local always wins
-- `remote-wins` - Server is authority
-- `merge` - Custom merge function
-- `keep-both` - Duplicate records
-
-📖 **[Complete Offline Sync Guide](./guides/OFFLINE_SYNC.md)** - 8 real-world examples with mobile optimization
-
-## Cloud Backups
-
-Automatic S3-compatible backups (AWS S3, Cloudflare R2, MinIO):
-
-```typescript
-import { S3Client } from '@aws-sdk/client-s3';
-import { createCloudBackupManager } from '@framers/sql-storage-adapter';
-
-const s3 = new S3Client({
-  region: 'us-east-1',
-  credentials: {
-    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
-    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
-  }
-});
-
-const manager = createCloudBackupManager(db, s3, 'my-backups', {
-  interval: 3600000,  // Hourly backups
-  maxBackups: 24,     // Keep 24 backups
-  options: { compression: 'gzip' }
-});
-
-manager.start();  // Auto-backup every hour
-
-// Manual backup
-await manager.backupNow();
-
-// Restore
-await manager.restore('backups/my-database-2024-01-15.json.gz');
-```
-
-## Data Migration
-
-Export, import, and migrate between adapters:
-
-```typescript
-import { 
-  migrateLocalToSupabase,
-  exportAsJSON,
-  importFromJSON 
-} from '@framers/sql-storage-adapter';
-
-// Export to JSON
-const backup = await exportAsJSON(db, { 
-  tables: ['users', 'posts'],
-  includeSchema: true 
-});
-
-// Import from JSON
-await importFromJSON(db, backup, {
-  dropTables: true,
-  batchSize: 100
-});
-
-// Migrate SQLite → PostgreSQL
-const result = await migrateLocalToSupabase(sqliteDb, postgresDb, {
-  verify: true,
-  onConflict: 'replace'
-});
-
-console.log(`Migrated ${result.rowsImported} rows in ${result.duration}ms`);
-```
-
-## PostgreSQL Remote Connections
-
-Connect to hosted databases (AWS RDS, Heroku, Supabase, etc.):
-
-```typescript
-import { connectDatabase } from '@framers/sql-storage-adapter';
-
-// Auto-detect from DATABASE_URL
-const db = await connectDatabase(process.env.DATABASE_URL);
-
-// Or configure explicitly
-const db = await connectDatabase({
-  host: 'db.example.com',
-  database: 'myapp',
-  user: 'dbuser',
-  password: process.env.DB_PASSWORD,
-  ssl: true,
-  max: 20  // Connection pool size
-});
-
-// Same API as SQLite!
-const users = await db.all('SELECT * FROM users');
-```
-
-📖 **[PostgreSQL Remote Guide](./guides/POSTGRES_REMOTE_CONNECTION.md)** - Cloud provider examples & SSL config
-
-## Adapter Comparison
-
-| Adapter | Best For | Speed | Size | Concurrent |
-|---------|----------|-------|------|------------|
-| **PostgreSQL** | Production servers | ⚡⚡⚡ | N/A | ✅ Yes |
-| **better-sqlite3** | Desktop apps | ⚡⚡⚡ | 6 MB | ❌ No |
-| **SQL.js** | Browsers | ⚡ | 2.3 MB | ❌ No |
-| **Capacitor** | Mobile apps | ⚡⚡⚡ | ~1 MB | ❌ No |
-
-## TypeScript Support
-
-Full type safety with generics:
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-  email: string;
-}
-
-// Type-safe queries
-const user = await db.get<User>('SELECT * FROM users WHERE id = ?', [1]);
-// user: User | null
-
-const users = await db.all<User>('SELECT * FROM users');
-// users: User[]
-
-// Runtime introspection
-const context = db.context;
-console.log('Adapter:', db.kind);
-console.log('Capabilities:', Array.from(db.capabilities));
-console.log('Max connections:', context.getLimitations().maxConnections);
-```
-
-## Event Monitoring
-
-Track queries and performance:
-
-```typescript
-db.events.on('query:error', (event) => {
-  console.error('Query failed:', event.statement, event.error);
-});
-
-db.events.on('performance:slow-query', (event) => {
-  if (event.duration > 1000) {
-    console.warn(`Slow query (${event.duration}ms):`, event.statement);
-  }
-});
-
-db.events.on('transaction:rollback', (event) => {
-  console.warn('Transaction rolled back:', event.error);
-});
-```
-
-## Examples
-
-Real-world usage in `examples/`:
-- `basic-usage.ts` - Getting started
-- `remote-postgres.ts` - Cloud database connections
-- `electron-app/` - Desktop app with better-sqlite3
-- `browser-extension/` - Chrome extension with SQL.js
-- `full-stack/` - Shared code frontend/backend
-- `offline-sync.ts` - Auto-sync patterns
-- `testing/` - Unit testing strategies
-
-## FAQ
-
-**Q: Which adapter should I use?**  
-Use `createDatabase()` - it auto-picks the best adapter for your environment.
-
-**Q: Can I switch adapters later?**  
-Yes. Use migration functions to move data between adapters.
-
-**Q: Is this production-ready?**  
-Yes. Built on battle-tested libraries (pg, better-sqlite3, sql.js). The adapter layer adds <1% overhead.
-
-**Q: What about schema migrations?**  
-Use any migration tool: [`node-pg-migrate`](https://github.com/salsita/node-pg-migrate), [`prisma`](https://www.prisma.io/), or raw SQL.
-
-**Q: How do I handle conflicts in sync?**  
-Use `conflictStrategy`: `last-write-wins` (default), `local-wins`, `remote-wins`, `merge`, or `keep-both`.
-
-**Q: Can I sync only on WiFi?**  
-Yes. Use `mode: 'manual'` and call `sync()` when `isOnWiFi === true`. See [Offline Sync Guide](./guides/OFFLINE_SYNC.md#1-mobile-app-with-wifi-only-sync).
-
-## Documentation
-
-- **[API Documentation](https://wearetheframers.github.io/sql-storage-adapter/)** - Complete TypeDoc reference
-- **[Offline Sync Guide](./guides/OFFLINE_SYNC.md)** - Comprehensive sync patterns
-- **[PostgreSQL Guide](./guides/POSTGRES_REMOTE_CONNECTION.md)** - Remote database setup
-- **[Architecture](./ARCHITECTURE.md)** - Design decisions
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md)
-
-## License
-
-MIT © [The Framers](https://frame.dev)
+# SQL Storage Adapter
+
+<p align="center">
+  <a href="https://frame.dev" target="_blank" rel="noopener">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./logos/frame-square-blue-dark-no-tagline.svg">
+      <source media="(prefers-color-scheme: light)" srcset="./logos/frame-square-blue-no-tagline.svg">
+      <img src="./logos/frame-square-blue-no-tagline.svg" alt="Frame.dev" width="200">
+    </picture>
+  </a>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@framers/sql-storage-adapter.svg?logo=npm&label=npm)](https://www.npmjs.com/package/@framers/sql-storage-adapter)
+[![CI](https://github.com/framersai/sql-storage-adapter/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/framersai/sql-storage-adapter/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/framersai/sql-storage-adapter/branch/master/graph/badge.svg)](https://codecov.io/gh/framersai/sql-storage-adapter)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/@framers/sql-storage-adapter.svg)](./LICENSE)
+
+> Cross-platform SQL access for Node.js, web, and native runtimes with automatic adapter selection and consistent APIs.
+
+The SQL Storage Adapter provides a single, ergonomic interface over SQLite (native and WASM), PostgreSQL, Capacitor, IndexedDB, and in-memory stores. It handles adapter discovery, capability detection, and advanced features like cloud backups so you can focus on your application logic.
+
+**🆕 NEW:** Full IndexedDB support for browser-native, offline-first web apps!
+
+---
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [AgentOS Integration](#agentos-integration)
+- [Adapter Matrix](#adapter-matrix)
+- [Configuration & Resolution](#configuration--resolution)
+- [Platform Strategy](#platform-strategy)
+- [CI, Releases, and Badges](#ci-releases-and-badges)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- **Auto-detected adapters** – `createDatabase()` inspects environment signals and picks the best backend (native SQLite, PostgreSQL, Capacitor, sql.js, **IndexedDB**, memory, etc.).
+- **Capability-aware API** – consistent CRUD, transactions, batching, and event hooks across adapters with runtime capability introspection.
+- **🆕 IndexedDB** – Browser-native persistence with sql.js for full SQL support in PWAs and offline-first apps.
+- **Cloud backups & migrations** – built-in backup manager with compression, retention policies, and restore helpers plus migration utilities.
+- **Portable packaging** – optional native dependencies; falls back to pure TypeScript/WASM adapters when native modules are unavailable.
+- **AgentOS-first** – Pre-configured schema, typed queries, and auto-detection for AgentOS deployments.
+- **CI-first design** – Vitest coverage, Codecov integration, and GitHub Actions workflows for linting, testing, releasing, and npm publish/tag automation.
+
+## Installation
+
+```bash
+# Core package
+npm install @framers/sql-storage-adapter
+
+# Install only the adapters you plan to use
+npm install better-sqlite3            # Native SQLite for Node/Electron
+npm install pg                        # PostgreSQL
+npm install @capacitor-community/sqlite  # Capacitor / mobile
+npm install sql.js                    # WASM SQLite (auto-included for IndexedDB)
+# IndexedDB uses sql.js (no extra install needed)
+```
+
+> Windows users: ensure the Visual Studio Build Tools (C++ workload) are installed before adding `better-sqlite3`. On Linux, install `python3`, `build-essential`, and `libssl-dev` prior to `npm install`.
+
+> Note: If `better-sqlite3` cannot be required, install native build tools before `npm install`, ensure your Node version matches available prebuilt binaries, or fall back to `sql.js` or `indexeddb` by setting `STORAGE_ADAPTER=sqljs` or `STORAGE_ADAPTER=indexeddb`.
+
+## Quick Start
+
+```typescript
+import { createDatabase } from '@framers/sql-storage-adapter';
+
+async function main() {
+  // Automatically selects the best adapter for the current runtime
+  const db = await createDatabase();
+
+  await db.exec(`
+    CREATE TABLE IF NOT EXISTS todos (
+      id INTEGER PRIMARY KEY,
+      task TEXT NOT NULL,
+      done INTEGER DEFAULT 0
+    )
+  `);
+
+  await db.run('INSERT INTO todos (task) VALUES (?)', ['Ship cross-platform builds']);
+  const items = await db.all<{ id: number; task: string; done: number }>('SELECT * FROM todos');
+  console.log(items);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error('Database bootstrap failed', error);
+  process.exit(1);
+});
+```
+
+## AgentOS Integration
+
+### Recommended: `createAgentOSStorage()`
+
+The easiest way to use sql-storage-adapter with AgentOS is the **AgentOS-first API**:
+
+```typescript
+import { createAgentOSStorage } from '@framers/sql-storage-adapter/agentos';
+import { AgentOS } from '@agentos/core';
+
+// Auto-detects platform (web, electron, capacitor, node, cloud)
+const storage = await createAgentOSStorage({
+  platform: 'auto',  // Detects best adapter
+  persistence: true,
+});
+
+const agentos = new AgentOS();
+await agentos.initialize({
+  storageAdapter: storage.getAdapter(),  // 🆕 New field in AgentOSConfig
+  // ... other config
+});
+```
+
+**Features:**
+- ✅ Auto-creates AgentOS tables (conversations, sessions, personas, telemetry)
+- ✅ Platform detection (web → IndexedDB, electron → better-sqlite3, etc.)
+- ✅ Typed query builders for common operations
+- ✅ Graceful degradation (e.g., IndexedDB → sql.js fallback)
+
+### Platform-Specific Examples
+
+```typescript
+// Web (Browser): Uses IndexedDB
+const webStorage = await createAgentOSStorage({ platform: 'web' });
+
+// Desktop (Electron): Uses better-sqlite3
+const desktopStorage = await createAgentOSStorage({ platform: 'electron' });
+
+// Mobile (Capacitor): Uses native SQLite
+const mobileStorage = await createAgentOSStorage({ platform: 'capacitor' });
+
+// Cloud (Node): Uses PostgreSQL
+const cloudStorage = await createAgentOSStorage({ 
+  platform: 'cloud',
+  postgres: { connectionString: process.env.DATABASE_URL }
+});
+```
+
+See [Platform Strategy Guide](./docs/PLATFORM_STRATEGY.md) for detailed pros/cons and architecture.
+
+## Adapter Matrix
+
+| Adapter | Package | Ideal for | Pros | Considerations |
+| --- | --- | --- | --- | --- |
+| **🆕 `indexeddb`** | bundled | **Browsers, PWAs** | Browser-native, async, 50MB-1GB+ quota, SQL via sql.js, offline-first | IndexedDB quotas vary, WASM overhead for SQL |
+| `better-sqlite3` | `better-sqlite3` | Node/Electron, CLI, CI | Native performance, transactional semantics, WAL support | Needs native toolchain; version must match Node ABI |
+| `postgres` | `pg` | Hosted or on-prem PostgreSQL | Connection pooling, rich SQL features, cloud friendly | Requires `DATABASE_URL`/credentials |
+| `sqljs` | bundled | Browsers, serverless edge, native fallback | Pure WASM, no native deps | Write performance limited vs native, optional persistence |
+| `capacitor` | `@capacitor-community/sqlite` | Mobile (iOS/Android, Capacitor) | Native SQLite on mobile, encryption | Requires Capacitor runtime |
+| `memory` | built-in | Unit tests, storybooks, constrained sandboxes | Zero dependencies, instant startup | Non-durable, single-process only |
+
+### Platform Priorities
+
+| Platform | Primary Adapter | Fallback | Use Case |
+|----------|----------------|----------|----------|
+| **Web (Browser)** | IndexedDB | sql.js | PWAs, offline-first web apps |
+| **Electron (Desktop)** | better-sqlite3 | sql.js | Desktop apps, dev tools |
+| **Capacitor (Mobile)** | capacitor | IndexedDB | iOS/Android native apps |
+| **Node.js** | better-sqlite3 | Postgres, sql.js | CLI tools, local servers |
+| **Cloud (Serverless)** | Postgres | better-sqlite3 | Multi-tenant SaaS, APIs |
+
+## Configuration & Resolution
+
+- `resolveStorageAdapter` inspects:
+  - explicit options (`priority`, `type`, adapter configs),
+  - environment variables (`STORAGE_ADAPTER`, `DATABASE_URL`),
+  - runtime hints (Capacitor detection, browser globals, IndexedDB availability).
+- Adapters are attempted in priority order until one opens successfully; a `StorageResolutionError` includes the full failure chain.
+- Provide `priority: ['indexeddb', 'sqljs']` for browser bundles or tests where native modules shouldn't load.
+- Use `createCloudBackupManager` for S3-compatible backups with gzip compression and retention limits.
+
+### IndexedDB-Specific Config
+
+```typescript
+import { IndexedDbAdapter } from '@framers/sql-storage-adapter';
+
+const adapter = new IndexedDbAdapter({
+  dbName: 'my-app-db',       // IndexedDB database name
+  storeName: 'sqliteDb',     // Object store name
+  autoSave: true,            // Auto-save to IndexedDB after writes
+  saveIntervalMs: 5000,      // Batch writes every 5s
+});
+
+await adapter.open();
+```
+
+**Key Features:**
+- ✅ Transactions (via sql.js)
+- ✅ Persistence (IndexedDB)
+- ✅ Export/import (Uint8Array SQLite file format)
+- ✅ Auto-save with batching (reduce IDB overhead)
+
+## Platform Strategy
+
+See [**PLATFORM_STRATEGY.md**](./docs/PLATFORM_STRATEGY.md) for a comprehensive guide on:
+- Graceful degradation patterns
+- Platform-specific pros/cons
+- Performance benchmarks
+- Offline-first architectures
+- AgentOS-specific recommendations
+
+**TL;DR:** Use IndexedDB for web, better-sqlite3 for desktop, capacitor for mobile, Postgres for cloud.
+
+## CI, Releases, and Badges
+
+- GitHub Actions workflows:
+  - `ci.yml` runs lint, tests, and coverage on every branch.
+  - `release.yml` publishes new versions to npm, tags the commit (`vX.Y.Z`), and creates/updates the GitHub Release when `CHANGELOG.md` and `package.json` bump the version.
+- Check badge health whenever builds fail:
+  - CI badge should be green for `master`.
+  - Codecov badge updates after coverage reports upload.
+  - npm badge reflects the latest published version.
+- Manual verification commands:
+  ```bash
+  npm info @framers/sql-storage-adapter version
+  pnpm --filter sql-storage-adapter test
+  pnpm --filter sql-storage-adapter build
+  ```
+- See [RELEASING.md](./RELEASING.md) for the automated release flow, required secrets (`NPM_TOKEN`), and manual fallback steps.
+
+ 
+
+## Contributing
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for coding standards, lint/test commands, and pull request guidelines.
+- Architecture notes live in [ARCHITECTURE.md](./ARCHITECTURE.md); API docs can be regenerated with `pnpm --filter sql-storage-adapter run docs`.
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+<p align="center">
+  Built and maintained by <a href="https://frame.dev" target="_blank" rel="noopener">Frame.dev</a>
+</p>