docs: align SQL DDL syntax, HTTP routes, and protocol handshake with current API

Update all examples and reference tables to reflect the current engine
selector syntax (`WITH (engine='...')` instead of `TYPE X`), the `/v1/`
route prefix for all data endpoints, versioned Content-Type headers, the
corrected health probe paths (`/healthz`, `/health/live`, `/health/ready`),
and the native protocol handshake/limits/capabilities documentation.

Also adds a PostgreSQL compatibility section to the SQL overview, expands
the vector-search page with hybrid and multi-vector query patterns, and
documents the DDL constraint policy.

Author: farhan-syah

docs/administration/authentication.rdx

@@ -26,7 +26,7 @@ DROP API KEY 'my-service';
 ```
 
 ```bash
-curl -H "Authorization: Bearer <api-key>" http://localhost:6480/query
+curl -H "Authorization: Bearer <api-key>" http://localhost:6480/v1/query
 ```
 
 ## JWKS (JWT)

docs/administration/monitoring.rdx

@@ -38,7 +38,8 @@ Feature-gated: `--features otel`, `--features promql`, `--features monitoring`.
 ## Health Checks
 
 ```bash
-curl http://localhost:6480/health        # basic health
+curl http://localhost:6480/healthz        # k8s readiness — 503 until startup completes
+curl http://localhost:6480/health/live    # liveness probe
 curl http://localhost:6480/health/ready   # WAL recovered, ready for queries
 ```
 

docs/architecture/overview.rdx

@@ -39,7 +39,7 @@ If code needs to cross a plane boundary, it goes through the SPSC bridge (Contro
 **SQL path** — All user-facing interfaces accept SQL. The Control Plane parses via sqlparser, plans via EngineRules, and dispatches a `SqlPlan` through the SPSC bridge to the Data Plane.
 
 ```
-psql / ndb CLI / HTTP /query
+psql / ndb CLI / HTTP /v1/query
   → SQL parser (sqlparser-rs)
   → EngineRules::plan_*()
   → SqlPlan → SPSC Bridge → Data Plane

docs/columnar-profiles/spatial.rdx

@@ -10,13 +10,13 @@ Spatial is a columnar profile. Collections with a `SPATIAL_INDEX` column modifie
 ## DDL
 
 ```sql
--- Columnar with spatial index
-CREATE COLLECTION restaurants TYPE COLUMNAR (
+-- Spatial peer engine (R-tree + geohash + OGC predicates)
+CREATE COLLECTION restaurants (
     location GEOMETRY SPATIAL_INDEX,
     name VARCHAR,
     cuisine VARCHAR,
     rating FLOAT
-);
+) WITH (engine='spatial');
 
 -- Or add a spatial index to any collection
 CREATE COLLECTION restaurants;
@@ -66,10 +66,10 @@ WKB, WKT, and GeoJSON interchange. GeoParquet v1.1.0 and GeoArrow metadata for b
 
 ```sql
 -- Fleet tracking: spatial + time
-CREATE COLLECTION fleet TYPE COLUMNAR (
+CREATE COLLECTION fleet (
     ts TIMESTAMP TIME_KEY,
     vehicle_id VARCHAR,
     position GEOMETRY SPATIAL_INDEX,
     speed FLOAT
-) WITH profile = 'timeseries', partition_by = '1d';
+) WITH (engine='timeseries', partition_by='1d');
 ```

docs/columnar-profiles/timeseries.rdx

@@ -10,13 +10,13 @@ Timeseries is a columnar profile. It extends the columnar engine with retention
 ## DDL
 
 ```sql
-CREATE COLLECTION cpu_metrics TYPE COLUMNAR (
+CREATE COLLECTION cpu_metrics (
     ts TIMESTAMP TIME_KEY,
     host VARCHAR,
     region VARCHAR,
     cpu_usage FLOAT,
     mem_usage FLOAT
-) WITH profile = 'timeseries', partition_by = '1d', retention = '90d';
+) WITH (engine='timeseries', partition_by='1d', retention='90d');
 
 -- Convenience alias
 CREATE TIMESERIES cpu_metrics;

docs/connectivity/http-api.rdx

@@ -12,23 +12,25 @@ REST API on port 6480 for web clients and services.
 ### Execute SQL
 
 ```bash
-curl -X POST http://localhost:6480/query \
+curl -X POST http://localhost:6480/v1/query \
   -H "Authorization: Bearer ndb_..." \
   -H "Content-Type: application/json" \
+  -H "Accept: application/vnd.nodedb.v1+json" \
   -d '{"sql": "SELECT * FROM users LIMIT 10"}'
 ```
 
 ### Stream Results (NDJSON)
 
 ```bash
-curl -X POST http://localhost:6480/query/stream \
+curl -X POST http://localhost:6480/v1/query/stream \
   -d '{"sql": "SELECT * FROM large_table"}'
 ```
 
 ### Health & Readiness
 
 ```bash
-curl http://localhost:6480/health        # basic health
+curl http://localhost:6480/healthz        # k8s readiness — 503 until startup completes
+curl http://localhost:6480/health/live    # liveness probe
 curl http://localhost:6480/health/ready   # WAL recovered, ready for queries
 ```
 
@@ -43,7 +45,7 @@ curl http://localhost:6480/metrics
 ### PromQL
 
 ```
-http://localhost:6480/obsv/api
+http://localhost:6480/v1/obsv/api
 ```
 
 Full Prometheus query engine. Point Grafana at this URL as a Prometheus data source.
@@ -57,4 +59,8 @@ GET /v1/streams/{stream}/poll?group={group}      # Long-poll
 
 ### WebSocket
 
-`/ws` endpoint for JSON-RPC: SQL execution, LIVE SELECT delivery, session reconnect.
+`/v1/ws` endpoint for JSON-RPC: SQL execution, LIVE SELECT delivery, session reconnect.
+
+## Versioning
+
+All non-probe routes are under the `/v1/` prefix. JSON responses carry `Content-Type: application/vnd.nodedb.v1+json; charset=utf-8`. Clients may opt into version negotiation by sending `Accept: application/vnd.nodedb.v1+json`; sending only an unsupported `application/vnd.nodedb.vN+json` returns `406 Not Acceptable`. Probe routes (`/healthz`, `/health/*`, `/metrics`) are unversioned and always reachable, including during startup.

docs/connectivity/native-protocol.rdx

@@ -32,3 +32,67 @@ Both modes produce the same `PhysicalPlan` and execute identically.
 ./target/release/ndb
 ./target/release/ndb --host localhost --port 6433
 ```
+
+## Handshake
+
+Every native connection performs a versioned handshake before any opcode frame. SDKs do this automatically on first use; you only need this section if you're implementing a wire-level client.
+
+### `HelloFrame` (client → server)
+
+| Field          | Width | Value                                   |
+| -------------- | ----- | --------------------------------------- |
+| `magic`        | 4 B   | `NDBH`                                  |
+| `proto_min`    | u16   | Minimum protocol version client accepts |
+| `proto_max`    | u16   | Maximum protocol version client supports |
+| `capabilities` | u64   | Bitmask of optional features (send `0` for none; unknown bits ignored by server) |
+
+### `HelloAckFrame` (server → client)
+
+| Field            | Width                | Value                                                 |
+| ---------------- | -------------------- | ----------------------------------------------------- |
+| `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"`)      |
+| `limits`         | `Limits` struct      | Per-op caps the server enforces (see below)           |
+
+### `HelloErrorFrame`
+
+Returned when no protocol version overlaps. Carries a typed `code` (`VersionMismatch`) and a UTF-8 reason. The connection is closed after the frame is sent.
+
+### Server-enforced `Limits`
+
+The `HelloAckFrame` carries the server's per-op caps. SDKs surface these via `client.limits()`. Sending a request that exceeds a cap returns a typed `LimitExceeded { limit_name, value, max }` error.
+
+| Field                  | Type          | Caps                                            |
+| ---------------------- | ------------- | ----------------------------------------------- |
+| `max_vector_dim`       | `Option<u32>` | Vector embedding dimensionality                 |
+| `max_top_k`            | `Option<u32>` | `top_k` for any retrieval op                    |
+| `max_scan_limit`       | `Option<u32>` | Result set size for scans                       |
+| `max_batch_size`       | `Option<u32>` | Rows per batch INSERT/UPSERT                    |
+| `max_crdt_delta_bytes` | `Option<u32>` | Single CRDT delta payload                       |
+| `max_query_text_bytes` | `Option<u32>` | SQL text length                                 |
+| `max_graph_depth`      | `Option<u32>` | `MAX_DEPTH` for graph traversal                 |
+
+`None` means uncapped. Defaults are uncapped — operators set caps via configuration.
+
+## Capabilities
+
+`Capabilities` is a typed wrapper around the `u64` bitmask returned in `HelloAckFrame`. SDK consumers query specific features via accessor methods rather than testing raw bits, so feature additions never break clients:
+
+```rust
+let caps = client.capabilities();
+if caps.has_graphrag_fusion() { ... }
+if caps.has_continuous_aggregates() { ... }
+```
+
+The `Capabilities::has(bit)` escape hatch is available for forward compatibility, but typed accessors are preferred.
+
+## Server Identity
+
+```rust
+client.proto_version()   // u16 — negotiated protocol version
+client.server_version()  // String — server build identifier
+client.limits()          // &Limits — per-op caps
+client.capabilities()    // Capabilities — typed feature flags
+```

docs/data-modeling/collections.rdx

@@ -14,41 +14,46 @@ A collection is NodeDB's top-level data container — analogous to a table in Po
 CREATE COLLECTION users;
 
 -- Strict document (schema-enforced)
-CREATE COLLECTION orders TYPE DOCUMENT STRICT (
+CREATE COLLECTION orders (
     id UUID DEFAULT gen_uuid_v7(),
     customer_id UUID NOT NULL,
     total DECIMAL NOT NULL,
     status STRING DEFAULT 'pending'
-);
+) WITH (engine='document_strict');
 
 -- Columnar (analytics)
-CREATE COLLECTION events TYPE COLUMNAR (
+CREATE COLLECTION events (
     ts TIMESTAMP TIME_KEY,
     user_id UUID,
     event VARCHAR,
     duration_ms INT
-);
+) WITH (engine='columnar');
 
 -- Key-Value
-CREATE COLLECTION sessions TYPE KEY_VALUE (key TEXT PRIMARY KEY);
+CREATE COLLECTION sessions (key TEXT PRIMARY KEY) WITH (engine='kv');
 ```
 
 ## Storage Engines
 
-| Type              | DDL                     | Best for                                        |
-| ----------------- | ----------------------- | ----------------------------------------------- |
-| Document          | `CREATE COLLECTION x`   | Flexible data, prototyping, agent state          |
-| Document (strict) | `TYPE DOCUMENT STRICT`  | OLTP, transactions, known schemas                |
-| Columnar          | `TYPE COLUMNAR`         | Analytics, reporting, scan-heavy workloads        |
-| Key-Value         | `TYPE KEY_VALUE`        | Sessions, caches, counters, key-dominant access   |
+NodeDB has seven peer engines. Pick one per collection via `WITH (engine='<name>')`. The default (no `engine=`) is `document_schemaless`.
 
-Columnar collections can specialize via profiles:
+| Engine                | Selector                            | Best for                                          |
+| --------------------- | ----------------------------------- | ------------------------------------------------- |
+| `document_schemaless` | (default)                           | Flexible data, prototyping, agent state           |
+| `document_strict`     | `WITH (engine='document_strict')`   | OLTP, transactions, known schemas                 |
+| `columnar`            | `WITH (engine='columnar')`          | Analytics, reporting, scan-heavy workloads        |
+| `timeseries`          | `WITH (engine='timeseries')`        | Append-only metrics, retention, continuous aggs    |
+| `spatial`             | `WITH (engine='spatial')`           | Geo-primary workloads, R*-tree, OGC predicates    |
+| `kv`                  | `WITH (engine='kv')`                | Sessions, caches, counters, key-dominant access   |
+| `vector`              | `WITH (engine='vector', vector_field='emb')` | Vector-primary collections                |
 
-| Profile    | Column Modifier  | Extra capabilities                                |
-| ---------- | ---------------- | ------------------------------------------------- |
-| Plain      | (none)           | Full UPDATE/DELETE, general analytics              |
-| Timeseries | `TIME_KEY`       | Retention, continuous aggregation, ILP ingest      |
-| Spatial    | `SPATIAL_INDEX`  | R*-tree indexing, OGC predicates                  |
+Column modifiers add capabilities to any engine:
+
+| Modifier         | Effect                                                            |
+| ---------------- | ----------------------------------------------------------------- |
+| `TIME_KEY`       | Marks the time column (used by timeseries engine, allowed elsewhere) |
+| `SPATIAL_INDEX`  | R*-tree index on a `GEOMETRY` column                              |
+| `PRIMARY KEY`    | Row identity column (inline only — table-level not supported)     |
 
 ## Cross-Engine Indexes
 
@@ -75,10 +80,9 @@ GRAPH INSERT EDGE IN 'products' FROM 'products:p1' TO 'products:p2' TYPE 'simila
 Collections can be converted at any time without data loss:
 
 ```sql
-CONVERT COLLECTION users TO strict;
-CONVERT COLLECTION logs TO columnar;
+CONVERT COLLECTION users TO document_strict;
 CONVERT COLLECTION cache TO kv;
-CONVERT COLLECTION events TO document;
+CONVERT COLLECTION events TO document_schemaless;
 ```
 
 NodeDB infers the schema from existing documents when converting to strict mode.

docs/data-modeling/schemas-types.rdx

@@ -27,7 +27,7 @@ description: Data types, schema enforcement, typeguards, and schema evolution.
 
 **Schemaless** — No schema required. Fields can vary between documents. Types are inferred on insert. This is the default when you `CREATE COLLECTION x`.
 
-**Strict** — Schema is defined at creation time and enforced on every write. O(1) field extraction via binary tuple format. Created with `TYPE DOCUMENT STRICT (...)`.
+**Strict** — Schema is defined at creation time and enforced on every write. O(1) field extraction via binary tuple format. Created with `(...) WITH (engine='document_strict')`.
 
 ## Typeguards (Schemaless Validation)
 
@@ -58,7 +58,7 @@ ALTER TYPEGUARD ON users DROP age;
 VALIDATE TYPEGUARD ON users;
 
 -- Graduate to strict schema
-CONVERT COLLECTION users TO strict;
+CONVERT COLLECTION users TO document_strict;
 ```
 
 ## Schema Evolution (Strict Mode)

docs/indexes/hash-index.rdx

@@ -14,7 +14,7 @@ Keys are hashed to locate the value directly — no tree traversal. This provide
 ## Creating a KV Collection
 
 ```sql
-CREATE COLLECTION sessions TYPE KEY_VALUE (key TEXT PRIMARY KEY);
+CREATE COLLECTION sessions (key TEXT PRIMARY KEY) WITH (engine='kv');
 ```
 
 The `PRIMARY KEY` column is automatically hash-indexed.