Stage (#140)

* chore(docs): restructure security docs and enhance API Keys documentation

Separated Users and Roles & Privileges into dedicated pages for better organization. Completely rewrote API Keys documentation with detailed instructions for creating, managing, and using API keys. Cleaned up navigation structure and removed duplicate content.

* docs: update OffSync page for v1.5.0 UI redesign

- Remove outdated video imports (old UI recordings)
- Add Enabling/Disabling OffSync section with dialog flow
- Rewrite Configuration tab: Database ID + SQL snippet + Push Notifications
- Add Metrics tab section (active devices, upload/download bytes)
- Update intro to reflect 4-tab layout

* docs: add enable/disable OffSync video to offsync page

* docs: remove obsolete section "Advanced: RLS and SQLite Sync"

* docs: enhance OffSync documentation for Database ID and Push Notifications configuration

* docs: comment out video player for OffSync enable/disable functionality

---------

Co-authored-by: Andrea Donetti <andinux@gmail.com>

Author: TizianoT

sqlite-cloud/_nav.ts

@@ -287,7 +287,8 @@ const sidebarNav: SidebarNavStruct = [
   { title: "Webhooks", filePath: "webhooks", type: "inner", level: 0 },
   { title: "Pub/Sub", filePath: "pub-sub", type: "inner", level: 0 },
   //{ title: "Vector", filePath: "vector", type: "inner", level: 0 },
-  { title: "Users and Roles", filePath: "security", type: "inner", level: 0 },
+  { title: "Users", filePath: "users", type: "inner", level: 0 },
+  { title: "Roles & Privileges", filePath: "roles", type: "inner", level: 0 },
   { title: "API Keys", filePath: "apikey", type: "inner", level: 0 },
   { title: "Row-Level Security", filePath: "rls", type: "inner", level: 0 },
   { title: "OffSync", filePath: "offsync", type: "inner", level: 0 },

sqlite-cloud/platform/apikey.mdx

@@ -1,20 +1,75 @@
 ---
 title: Security and Access Control
-description: SQLite Cloud provides secure access to resources through role-based authorization, which ensures user isolation and enhances security and manageability.
+description: Manage API Keys for secure application access, server-to-server communication, and SDK integration.
 category: platform
 status: publish
 slug: apikey
 ---
 
-## API KEYs 
 
 API KEYs can be used as an alternative authentication mechanism.
 Authentication through API keys ensures the same privileges as the user to which they are associated.
 API KEYs are recommended for all server-to-server authentication cases and are necessary for using the REST APIs and the SDKs that uses the WebSocket APIs.
 
-To create an API key for a user, click on the **Create API KEY** button.
+You can manage all keys in your cluster via the SQLite Cloud Dashboard under the **API Keys** section.
 
-![Dashboard Create APIKEY](@docs-website-assets/introduction/dashboard_create_apikey.png)
+---
+
+## Creating an API Key
+
+You can create an API Key and immediately assign it to any existing user in your cluster.
+
+1. Navigate to the **API Keys** section in the left sidebar.
+2. Click the **Create API Key** button.
+3. **API Key Name:** Enter a descriptive name to identify the key (e.g., `MobileApp_Prod`, `Backend_Worker`).
+4. **User:** Select the user this key will impersonate from the dropdown list.
+5. **Expiration:**
+    *   Select **Never expires** for long-running services.
+    *   Select **Set expiration date** to enforce a rotation policy or for temporary access tokens.
+6. Click **Create**.
+
+[VIDEO: create_apikey_global.mp4]
+{/* <!-- Video showing the global creation flow: entering a name, selecting a user from the dropdown, picking a date, and creating --> */}
+
+---
+
+## Managing API Keys
+
+The API Keys list provides a centralized view of all active keys, their associated users, and expiration status.
+
+### Regenerating a Key
+If a key is lost, forgotten, or you suspect it has been compromised (leaked), you should regenerate it immediately.
+
+1. Find the key in the list.
+2. Click the context menu (three dots) on the right.
+3. Select **Regenerate**.
+4. Confirm the action in the modal window.
+
+**Warning:** Regenerating a key invalidates the old key string immediately. You must update any applications or scripts using the old key with the new value to restore connectivity.
+
+[VIDEO: regenerate_apikey.mp4]
+{/* <!-- Video showing the regenerate flow and the confirmation modal --> */}
+
+### Editing and Deleting
+*   **Edit:** Allows you to rename the key or change its expiration settings without changing the key string itself.
+*   **Delete:** Permanently revokes the key. Applications using this key will no longer be able to connect.
+
+[VIDEO: delete_apikey.mp4]
+{/* <!-- Video showing the delete action --> */}
+
+---
+
+## Using API Keys
+
+Once generated, the API Key is typically used in the connection string of your SQLite Cloud client or SDK.
+
+The standard format for a connection string using an API Key is:
+```
+sqlitecloud://<host>:<port>?apikey=<your-api-key>
+```
+
+When using the REST API directly, the key should be passed in the Authorization header:
 
-The resulting table will display all the API keys associated with each user, along with their name.
-![Dashboard List APIKEY](@docs-website-assets/introduction/dashboard_list_apikey.png)
+```http
+Authorization: Bearer <your-api-key>
+```

sqlite-cloud/platform/offsync.mdx

@@ -7,9 +7,6 @@ slug: offsync
 ---
 
 import VideoPlayer from '@commons-components/Video/VideoPlayer.astro';
-import enableSync from '@docs-website-assets/introduction/video/dashboard_sqlite_sync_enabling.mp4';
-import connectionUrlSync from '@docs-website-assets/introduction/video/dashboard_sync_connection_url.mp4';
-import devicesSync from '@docs-website-assets/introduction/video/dashboard_sync_devices.mp4';
 
 import Callout from "@commons-components/Information/Callout.astro";
 
@@ -31,35 +28,65 @@ OffSync extends standard SQLite tables with built-in support for offline work an
 When combined with [Row-Level Security (RLS)](/docs/rls), OffSync allows you to build secure, multi-tenant applications where each user's data is safely isolated, both on the edge and in the cloud.
 
 
---- 
+---
 
 ## Configuring OffSync
 
-You can enable and manage OffSync for your databases directly from the SQLite Cloud dashboard.  
-Below are the main steps:
+You can enable and manage OffSync for your databases directly from the SQLite Cloud dashboard.
+The OffSync panel has four tabs: **Sync Tables**, **Configuration**, **Devices**, and **Metrics**.
+
+### Enabling and Disabling OffSync
+
+When OffSync is not yet active for a database, the panel shows a brief explanation and an **Enable OffSync** button. Clicking it opens a confirmation dialog; after confirming, the database is registered with the sync service and the tabbed view appears.
+
+To disable OffSync, click the **Disable OffSync** button in the top-right corner of the panel and confirm the action in the dialog that appears.
+
+{/* <VideoPlayer src={enableDisableSync} /> */}
 
 ### Enable Tables for Synchronization
-From the **Sync Tables** tab, select which tables in your database you want to keep synchronized.  
+
+From the **Sync Tables** tab, select which tables in your database you want to keep synchronized.
 Once enabled, all changes to those tables will automatically sync with connected devices.
 
-<VideoPlayer src={enableSync} />
+{/* VIDEO: dashboard_offsync_sync_tables.mp4
+    Show: Sync Tables tab open → toggle one or more tables on → confirmation that sync is active for those tables. */}
+
+### Configuration Tab
 
+The **Configuration** tab contains two sub-sections:
 
-### Get the Connection String
-In the **Configuration** tab, copy the connection string.  
-Use this in your application to initialize OffSync and connect your local SQLite database with SQLite Cloud.
+**Database ID** — A read-only field showing the unique identifier for your OffSync-enabled database, with a copy button for convenience. Use this ID in your application to initialize the sync connection (see the <a href="https://github.com/sqliteai/sqlite-sync" target="_blank">sqlite-sync README</a> for more details):
 
-<VideoPlayer src={connectionUrlSync} />
+```sql
+SELECT cloudsync_network_init('<database-id>');
+```
 
+**Push Notifications** — Push notifications work out of the box. If you have enabled Expo enhanced security, provide your access token here. This is only required when using the `sqlite-sync-react-native` library with push mode enabled — the token adds an extra layer of security to prevent unauthorized push notifications.
+
+{/* VIDEO: dashboard_offsync_configuration.mp4
+    Show: Configuration tab open → Database ID field with copy button clicked → scroll down to Push Notifications section → paste an Expo token → save → status changes to "Working". */}
 
 ### Manage Connected Devices
-In the **Devices** tab, you can view all devices currently connected to your database.  
+
+In the **Devices** tab, you can view all devices currently connected to your database.
 Here you can check their sync status and remove devices if needed.
 
-<VideoPlayer src={devicesSync} />
+{/* VIDEO: dashboard_offsync_devices.mp4
+    Show: Devices tab open with a list of connected devices → inspect sync status of one device → remove a device from the list. */}
 
 <Callout type="note" title="Matching Schemas and Tables">
 For OffSync to work correctly, the list of tables configured for synchronization—and their corresponding schemas—must be identical in both your local SQLite database and your SQLite Cloud database.
 </Callout>
 
+### Metrics Tab
+
+The **Metrics** tab provides visibility into daily and cumulative usage for your OffSync-enabled database:
+
+- **Active devices** — number of devices that have synced within the period
+- **Upload bytes** — data sent from devices to SQLite Cloud
+- **Download bytes** — data sent from SQLite Cloud to devices
+
+{/* VIDEO: dashboard_offsync_metrics.mp4
+    Show: Metrics tab open → scroll through active devices chart → upload bytes chart → download bytes chart, ideally with some non-zero data visible. */}
+
 Once enabled, any changes made to the selected tables via the SQLite Sync extension will be automatically synchronized with your SQLite Cloud database.

sqlite-cloud/platform/pub-sub.mdx

@@ -6,7 +6,6 @@ status: publish
 slug: pub-sub
 ---
 
-# SQLiteCloud Pub/Sub System
 
 **Publish/Subscribe (Pub/Sub)** is a messaging pattern that enables asynchronous communication between multiple applications. In the context of **SQLiteCloud**, Pub/Sub provides a robust way to deliver real-time updates or custom messages to subscribed clients when data changes or explicit notifications are issued.
 

sqlite-cloud/platform/rls.mdx

@@ -254,24 +254,3 @@ OLD.status <> 'paid'
 
 **Explanation:**
 This policy uses the `OLD` reference to check the value of the `status` column *before* the update is applied. If the status is already `'paid'`, the condition `OLD.status <> 'paid'` will be false, and the `UPDATE` operation will be denied. This effectively makes paid invoices read-only.
-
-
---- 
-
-## Advanced: RLS and SQLite Sync
-
-When using RLS in conjunction with <a href="https://github.com/sqliteai/sqlite-sync" target="_blank">SQLite Sync</a>, it's important to understand how they interact. The Sync protocol applies changes on a column-by-column basis, which can affect how `INSERT` and `UPDATE` policies are evaluated.
-
-To accommodate this, SQLite Cloud offers two modes for handling RLS during sync operations, configurable via the `rls_mode` server setting using the SQLite Cloud builtin command `SET KEY rls_mode TO <value>`.
-
-#### Default Mode (`rls_mode = 1`)
-
-To simplify policy creation for the most common use cases, the default mode does **not** enforce `INSERT` and `UPDATE` policies while applying changes from SQLite Sync.
-
-Instead, after the sync operation is complete, the `SELECT` policy is used to validate the final state of the row. If the user does not have permission to view the resulting row, the entire transaction is rolled back. This ensures that users cannot introduce changes that they are not allowed to see.
-
-#### Manual Policy Mode (`rls_mode = 0`)
-
-For more complex scenarios, such as implementing separate read/write permissions or restricting write access to specific columns, you can set `rls_mode` to `0`.
-
-In this mode, your `INSERT` and `UPDATE` policies are enforced for every incremental change applied by SQLite Sync. Because of Sync's column-by-column operation, your policies must be written to permit intermediate states. This means the policies must allow `NEW` values for non-primary key columns to be temporarily set to their default values during the sync process.