docs: update SQL syntax and refine content across all doc sections

Revise OIDC provider DDL to use keyword-based syntax (ISSUER, JWKS_URI,
AUDIENCE, CLAIM MAPPING WHEN) instead of WITH (...) object notation,
aligning the reference docs with the implemented SQL grammar.

Add IF NOT EXISTS / IF EXISTS variants for CREATE INDEX and DROP INDEX,
document GRANT SELECT on COLLECTION/TABLE, and improve DROP DATABASE
FORCE/CASCADE descriptions in the DDL reference.

Expand and correct content in storage-engines (vector, graph, array,
timeseries), connectivity (pgwire, sync-protocol), crdt-sync (overview,
conflict-policies, constraint-validation), administration (auth, RBAC,
monitoring, multi-tenancy), and temporal/bitemporal pages.

Author: farhan-syah

docs/administration/authentication.rdx

@@ -11,39 +11,41 @@ NodeDB supports multiple authentication methods simultaneously.
 
 ```sql
 CREATE USER alice WITH PASSWORD 'strong_password';
+CREATE USER IF NOT EXISTS alice WITH PASSWORD 'strong_password';
 CREATE USER bob WITH PASSWORD 'secret' ROLE readonly;
+DROP USER alice;
+DROP USER IF EXISTS alice;
 ```
 
+`CREATE USER ... IF NOT EXISTS` and `DROP USER ... IF EXISTS` make user DDL idempotent.
+
 ```bash
 psql -h localhost -p 6432 -U alice
 ```
 
 ## API Keys
 
-### Basic API Key Usage
+API keys enable programmatic access for services and applications:
 
 ```sql
-CREATE API KEY 'my-service' ROLE readwrite;
-DROP API KEY 'my-service';
-```
-
-```bash
-curl -H "Authorization: Bearer <api-key>" http://localhost:6480/v1/query
+CREATE API KEY FOR alice [EXPIRES <seconds>] [WITH SCOPES '<scope>', ...] [WITH DATABASES (<db1>, <db2>)];
+LIST API KEYS FOR alice;        -- or SHOW API KEYS FOR alice
+REVOKE API KEY <key_id>;
 ```
 
-### Database Scoping
+- `FOR <user>` is mandatory
+- Key is shown once; store it securely
+- `EXPIRES` is seconds until revocation (optional)
+- `WITH SCOPES` restricts operations (e.g., 'read:collections', 'write:data')
+- `WITH DATABASES` restricts collection access (optional; empty = user's default databases)
 
-API keys can be scoped to specific databases, restricting the key's access:
+Example:
 
-```sql
-CREATE API KEY 'web-app' FOR user alice WITH DATABASES (prod_orders, prod_users);
-CREATE API KEY 'analytics' FOR user bob WITH DATABASES (analytics_db);
-
-SHOW API KEYS;    -- displays accessible_databases for each key
+```bash
+curl -H "Authorization: Bearer <api-key>" http://localhost:6480/v1/query \
+     -d '{"sql": "SELECT 1"}'
 ```
 
-An API key with an empty database list inherits the owner's accessible databases at bind time. A non-empty list is an explicit restriction — the key can only access the listed databases.
-
 ### Service Accounts
 
 Service accounts are privileged accounts designed for application-to-database connections:
@@ -52,7 +54,7 @@ Service accounts are privileged accounts designed for application-to-database co
 CREATE SERVICE ACCOUNT etl_worker FOR DATABASE analytics_db;
 ALTER SERVICE ACCOUNT etl_worker SET DATABASES (analytics_db, staging_db);
 
-CREATE API KEY 'etl-key' FOR SERVICE ACCOUNT etl_worker;
+CREATE API KEY FOR etl_worker WITH DATABASES (analytics_db);
 ```
 
 Service accounts are scoped to a single tenant (inherited from the caller) and support per-database access control, inheriting or narrowing their scope when API keys are created on them.

docs/administration/monitoring.rdx

@@ -43,6 +43,17 @@ curl http://localhost:6480/health/live    # liveness probe
 curl http://localhost:6480/health/ready   # WAL recovered, ready for queries
 ```
 
+## Graph Statistics
+
+For per-collection edge counts and graph cardinality, use `SHOW GRAPH STATS`:
+
+```sql
+SHOW GRAPH STATS 'collection_name' VERBOSE;
+SHOW GRAPH STATS 'collection_name' AS OF SYSTEM TIME <ms>;
+```
+
+See [Graph Engine](../storage-engines/graph) for complete `SHOW GRAPH STATS` documentation.
+
 ## Key Metrics
 
 | Metric Category | Examples                                       |
@@ -88,7 +99,7 @@ These metrics are emitted from the dispatch layer (qps), memory governor (memory
 
 ## Cross-shard transaction metrics
 
-| Metric | Type | Description |
+| Metric | Type | Description | 
 | ------ | ---- | ----------- |
 | `nodedb_sequencer_epochs_total` | counter | Epochs proposed by the sequencer |
 | `nodedb_sequencer_epoch_duration_ms` | histogram | Time to drain and propose each epoch |

docs/administration/multi-tenancy.rdx

@@ -24,6 +24,16 @@ CREATE TENANT acme;
 CREATE USER alice WITH PASSWORD 'secret' ROLE readwrite TENANT 42;
 ```
 
+### Superuser Session Tenant Switching
+
+A superuser can switch the session tenant at runtime:
+
+```sql
+SET TENANT = 'acme' | 1234 | DEFAULT;
+```
+
+This changes which tenant's data is visible for subsequent queries in the session. Non-superusers cannot use `SET TENANT`.
+
 ## Quotas
 
 ```sql

docs/administration/oidc-sso.rdx

@@ -18,46 +18,32 @@ NodeDB validates JWT bearer tokens against your OIDC provider's public key set (
 Register your OIDC provider's details:
 
 ```sql
-CREATE OIDC PROVIDER okta WITH (
-    issuer      = 'https://yourorgname.okta.com/',
-    jwks_url    = 'https://yourorgname.okta.com/.well-known/oauth2/default/v1/keys',
-    audience    = 'https://nodedb.example.com',
-    claim_mapping = [
-        { claim_name = 'email', claim_value = null, effect = {
-            default_database = 'self_service'
-          } },
-        { claim_name = 'groups', claim_value = 'engineering', effect = {
-            add_databases = ['engineering_prod'],
-            add_roles = ['data_analyst']
-          } }
-    ]
-);
+CREATE OIDC PROVIDER okta ISSUER 'https://yourorgname.okta.com/' JWKS_URI 'https://yourorgname.okta.com/.well-known/oauth2/default/v1/keys' AUDIENCE 'https://nodedb.example.com'
+  CLAIM MAPPING
+    WHEN email = null SET DEFAULT_DATABASE = 1
+    WHEN groups = 'engineering' SET ADD DATABASES [2] ADD ROLES ['data_analyst'];
 ```
 
 **Fields:**
 
-| Field | Required | Meaning |
-|-------|----------|---------|
-| `issuer` | Yes | Token issuer URL (e.g., https://accounts.google.com) |
-| `jwks_url` | Yes | Public key set URL for signature validation |
-| `audience` | Yes | Expected JWT `aud` claim; mismatches are rejected |
-| `claim_mapping` | Yes | Array of rules mapping JWT claims to NodeDB identity fields |
+**Syntax:**
+- `ISSUER '<url>'` — Token issuer URL (e.g., https://accounts.google.com)
+- `JWKS_URI '<url>'` — Public key set URL for signature validation
+- `AUDIENCE '<aud>'` — (optional) Expected JWT `aud` claim; mismatches are rejected
+- `CLAIM MAPPING WHEN ... [SET DEFAULT_DATABASE = <id>] [ADD DATABASES [...]] [ADD ROLES [...]]` — Rules mapping JWT claims to NodeDB identity
 
 NodeDB fetches the JWKS once, caches it in memory, and refreshes it when:
 - A token arrives with an unknown key ID (`kid`)
 - The cache TTL expires (typically 24 hours)
-- You explicitly reload via `ALTER OIDC PROVIDER ... REFRESH JWKS`
 
 ## Claim Mapping
 
-Claim mapping rules translate JWT claims into NodeDB identity fields and access grants. Each rule specifies:
+Claim mapping rules translate JWT claims into NodeDB identity fields and access grants. Each rule in the `CLAIM MAPPING` clause specifies:
 
-- `claim_name` — JWT claim name to match (e.g., `email`, `groups`, `org_id`)
-- `claim_value` — (optional) specific value to match; if omitted, rule applies to all values
-- `effect` — what happens when the rule matches:
-  - `default_database` — set as the user's default database for queries
-  - `add_databases` — grant access to these databases
-  - `add_roles` — assign these roles to the session
+- `WHEN <claim> = '<value>'` — JWT claim name and value to match (e.g., `WHEN email = 'alice@example.com'` or `WHEN groups = 'engineering'`)
+- `SET DEFAULT_DATABASE = <db_id>` — (optional) set as the user's default database (numeric ID)
+- `ADD DATABASES [<id>, ...]` — (optional) grant access to these databases (numeric IDs)
+- `ADD ROLES ['<role>', ...]` — (optional) assign these roles to the session (quoted role names)
 
 **Example**: An Okta JWT like:
 
@@ -73,18 +59,11 @@ Claim mapping rules translate JWT claims into NodeDB identity fields and access
 Maps to:
 
 ```sql
-claim_mapping = [
-    { claim_name = 'email', claim_value = null, effect = {
-        default_database = 'analytics'
-      } },
-    { claim_name = 'groups', claim_value = 'engineering', effect = {
-        add_databases = ['engineering_db'],
-        add_roles = ['data_analyst']
-      } },
-    { claim_name = 'groups', claim_value = 'admins', effect = {
-        add_roles = ['cluster_admin']
-      } }
-]
+CREATE OIDC PROVIDER okta ISSUER 'https://yourorgname.okta.com/' JWKS_URI 'https://...' AUDIENCE 'api'
+  CLAIM MAPPING
+    WHEN email = 'alice@acme.com' SET DEFAULT_DATABASE = 2
+    WHEN groups = 'engineering' ADD DATABASES [3] ADD ROLES ['data_analyst']
+    WHEN groups = 'admins' ADD ROLES ['cluster_admin'];
 ```
 
 The session inherits all matching rules' effects. If multiple rules grant database access, the union is used.
@@ -96,26 +75,16 @@ The session inherits all matching rules' effects. If multiple rules grant databa
 
 ## Updating a Provider
 
-Modify JWKS URL, audience, or claim mappings after creation:
+Replace the claim mapping rules after creation:
 
 ```sql
-ALTER OIDC PROVIDER okta SET (
-    audience = 'https://api.example.com'
-);
-
-ALTER OIDC PROVIDER okta SET (
-    claim_mapping = [
-        { claim_name = 'email', claim_value = null, effect = {
-            default_database = 'analytics'
-          } },
-        { claim_name = 'dept_name', claim_value = 'sales', effect = {
-            add_databases = ['sales_db'],
-            add_roles = ['sales_role']
-          } }
-    ]
-);
+ALTER OIDC PROVIDER okta SET CLAIM MAPPING
+    WHEN email = 'alice@acme.com' SET DEFAULT_DATABASE = 2
+    WHEN dept_name = 'sales' ADD DATABASES [5] ADD ROLES ['sales_role'];
 ```
 
+`ALTER OIDC PROVIDER ... SET CLAIM MAPPING` replaces the full rule set. To change the issuer, JWKS URI, or audience, drop and recreate the provider.
+
 Changes take effect immediately for new logins. Existing sessions tied to the provider remain valid until token expiry.
 
 ## Listing Providers
@@ -126,23 +95,14 @@ See all configured OIDC providers:
 SHOW OIDC PROVIDERS;
 ```
 
-**Output columns:**
-
-| Column | Meaning |
-|--------|---------|
-| `name` | Provider name (e.g., `okta`) |
-| `issuer` | Token issuer URL |
-| `audience` | Expected `aud` claim |
-| `jwks_url` | Public key set URL |
-| `claim_mapping` | Array of mapping rules (summary) |
-| `created_at` | Timestamp |
+**Output includes provider name, issuer, audience, JWKS URI, claim mapping rules, and creation timestamp.**
 
 ## Removing a Provider
 
 Drop a provider:
 
 ```sql
-DROP OIDC PROVIDER okta;
+DROP OIDC PROVIDER IF EXISTS okta;
 ```
 
 Existing sessions using tokens from that provider are revoked at their next request.
@@ -167,19 +127,13 @@ NodeDB validates tokens in this order:
 ### Step 1: Configure the Provider
 
 ```sql
-CREATE OIDC PROVIDER auth0 WITH (
-    issuer   = 'https://your-tenant.us.auth0.com/',
-    jwks_url = 'https://your-tenant.us.auth0.com/.well-known/jwks.json',
-    audience = 'https://api.example.com',
-    claim_mapping = [
-        { claim_name = 'email', claim_value = null, effect = {
-            default_database = 'production'
-          } },
-        { claim_name = 'https://api.example.com/roles', claim_value = 'readwrite', effect = {
-            add_roles = ['readwrite']
-          } }
-    ]
-);
+CREATE OIDC PROVIDER auth0
+  ISSUER 'https://your-tenant.us.auth0.com/'
+  JWKS_URI 'https://your-tenant.us.auth0.com/.well-known/jwks.json'
+  AUDIENCE 'https://api.example.com'
+  CLAIM MAPPING
+    WHEN email = null SET DEFAULT_DATABASE = 1
+    WHEN https://api.example.com/roles = 'readwrite' ADD ROLES ['readwrite'];
 ```
 
 ### Step 2: Get a Token from Auth0
@@ -204,14 +158,14 @@ curl -H "Authorization: Bearer eyJhbGciOi..." \
      -d '{"sql": "SELECT 1"}'
 ```
 
-Or via native protocol (e.g., with `nodedb-client`):
+Or via native protocol (e.g., with `nodedb-client`) on port 6433:
 
 ```rust
 let auth = AuthMethod::OidcBearer {
     token: "eyJhbGciOi...".to_string(),
     provider: "auth0".to_string(),
 };
-let session = nodedb_client::connect("localhost:6432", auth).await?;
+let session = nodedb_client::connect("localhost:6433", auth).await?;
 ```
 
 ### Step 4: Query as the Authenticated User
@@ -301,7 +255,7 @@ Regular users cannot modify providers.
 ## Troubleshooting
 
 **Token rejected: invalid signature**
-- JWKS cache may be stale. Manually refresh: `ALTER OIDC PROVIDER <name> REFRESH JWKS`
+- JWKS cache may be stale; it will auto-refresh on next unknown key ID
 - Check that the issuer matches exactly (including trailing `/`)
 
 **Token rejected: audience mismatch**

docs/administration/rbac.rdx

@@ -11,8 +11,8 @@ description: Role-based access control with GRANT, REVOKE, and built-in role hie
 | -------------- | ------------------------------ |
 | `readonly`     | SELECT on all collections      |
 | `readwrite`    | SELECT, INSERT, UPDATE, DELETE |
-| `admin`        | All operations + DDL           |
 | `tenant_admin` | Admin within a tenant          |
+| `monitor`      | Read metrics, health, audit; no data access |
 | `superuser`    | Unrestricted (cross-tenant)    |
 | `cluster_admin` | Cluster-wide admin operations without full superuser capabilities |
 
@@ -78,19 +78,27 @@ Certain administrative DDL operations are gated by required roles. Attempting an
 
 ```sql
 CREATE ROLE analyst;
+CREATE ROLE IF NOT EXISTS analyst;
 CREATE ROLE data_engineer;
+DROP ROLE analyst;
+DROP ROLE IF EXISTS analyst;
 ```
 
+`CREATE ROLE ... IF NOT EXISTS` and `DROP ROLE ... IF EXISTS` make role DDL idempotent.
+
 ## Granting Permissions
 
 ```sql
-GRANT SELECT ON orders TO analyst;
-GRANT INSERT, UPDATE ON orders TO data_engineer;
+GRANT SELECT ON COLLECTION orders TO analyst;
+GRANT SELECT ON TABLE orders TO analyst;
+GRANT INSERT, UPDATE ON COLLECTION orders TO data_engineer;
 GRANT ALL ON orders TO admin;
 GRANT EXECUTE ON FUNCTION full_name TO analyst;
 GRANT BACKUP ON TENANT acme TO ops_user;
 ```
 
+`ON COLLECTION <name>` and `ON TABLE <name>` are explicit object-type keywords (default is collection if neither specified).
+
 ## Revoking
 
 ```sql

docs/connectivity/native-protocol.rdx

@@ -53,7 +53,7 @@ Every native connection performs a versioned handshake before any opcode frame.
 | `magic`          | 4 B                  | `NDBA`                                                |
 | `proto_version`  | u16                  | Negotiated version (`max(proto_min_client, proto_min_server) ≤ v ≤ min(proto_max_client, proto_max_server)`) |
 | `capabilities`   | u64                  | Server-side capability bitmask                        |
-| `server_version` | length-prefixed UTF-8 | Build identifier (e.g. `"nodedb 0.1.0+abc123"`)      |
+| `server_version` | length-prefixed UTF-8 | Build identifier (e.g. `"NodeDB/0.3.0"`)             |
 | `limits`         | `Limits` struct      | Per-op caps the server enforces (see below)           |
 
 ### `HelloErrorFrame`

docs/connectivity/pgwire.rdx

@@ -23,6 +23,40 @@ psql -h localhost -p 6432
 - Server-side cursors (SCROLL, BACKWARD, MOVE, WITH HOLD)
 - Temporary tables (session-scoped)
 
+## Introspection & Administration
+
+### SHOW Commands
+
+```sql
+SHOW ROLES;
+SHOW STATS;                        -- alias: SHOW SERVER STATS
+SHOW METRICS;
+SHOW MEMORY;
+SHOW TENANTS WITH NAME <name>;
+```
+
+`SHOW STATS` returns live query latencies, throughput, and resource usage. `SHOW METRICS` exports Prometheus-format metrics. `SHOW MEMORY` shows per-engine memory allocation and jemalloc stats.
+
+### SET Commands
+
+Session-level configuration:
+
+```sql
+SET TENANT = '<name>' | <id> | DEFAULT;  -- superuser only — switch session tenant
+```
+
+### pg_catalog Compatibility
+
+NodeDB exposes virtual `pg_catalog` tables for Postgres-client compatibility, BI tools, and ORM introspection:
+
+- `pg_class` — Collections and materialized views
+- `pg_namespace` — Databases and schemas
+- `pg_attribute` — Collection columns and types
+- `pg_index` — Index metadata
+- `pg_type` — Data types
+
+Tools like DBeaver, Tableau, and SQLAlchemy automatically query these tables. No special setup required.
+
 ## Compatible Clients
 
 Any PostgreSQL client library: libpq, JDBC, psycopg2, node-postgres, SQLAlchemy, Prisma, Diesel, tokio-postgres, and more.