docs: add telemetry design, test summary, and user guide

Rebases the docs PR onto main now that #327 has landed. Drops all code
changes from the diff; keeps only the new docs (docs/TELEMETRY.md,
spec/telemetry-design.md, spec/telemetry-test-completion-summary.md) and
swaps README's telemetry section to a short pointer to docs/TELEMETRY.md.

Co-authored-by: Isaac

Author: samikshya-db

README.md

@@ -53,88 +53,50 @@ client
 
 ## Telemetry
 
-Starting with version 1.13, the driver collects telemetry — connection,
-statement, and CloudFetch chunk metrics, plus error events with redacted
-stack traces — to help Databricks improve driver performance and
-reliability. **Telemetry is enabled by default and gated by a server-side
-feature flag**: events are emitted only when the workspace's feature flag
-is on. No SQL text, parameter values, or row data are ever included.
-
-### What's collected
-
-- Connection lifecycle (`CREATE_SESSION`, `DELETE_SESSION`) with latency.
-- Statement lifecycle (`STATEMENT_START`, `STATEMENT_COMPLETE`) with
-  execution latency, operation type, and result format.
-- CloudFetch chunk timings and byte counts.
-- Error events with redacted stack traces (Bearer/JWT tokens, OAuth
-  secrets, home-directory paths, and Databricks PATs are stripped before
-  emission).
-
-See `TelemetryEvent` and `TelemetryMetric` in the package exports for the
-exact payload shapes.
-
-### Multi-tenant SaaS deployments — read this before enabling telemetry
-
-The telemetry layer shares one per-host `TelemetryClient` across every
-`DBSQLClient` connected to the same Databricks workspace host. The
-authenticated export path uses the **first-registered** client's auth
-provider, User-Agent, and `telemetryAuthenticatedExport` value — these
-fields are snapshotted at the host singleton and are **not** per-tenant.
-
-If you are operating a SaaS layer that fronts multiple tenants against the
-same Databricks workspace host with a shared driver process, telemetry from
-tenant B's queries can be POSTed under tenant A's auth headers, with
-tenant A's `userAgentEntry`. A tenant B that explicitly set
-`telemetryAuthenticatedExport: false` will still ride tenant A's
-authenticated pipeline.
-
-> **Recommendation for multi-tenant deployments**: set
-> `telemetryEnabled: false` on all `DBSQLClient` instances, or partition
-> by Databricks workspace host so each tenant owns its own
-> `TelemetryClient`. Subsequent registrants with diverging auth/UA values
-> emit a warn-level log so the leak is at least visible.
-
-### Opting out
-
-Three independent ways to disable telemetry, in order of precedence:
-
-1. **Environment variable** — set `DATABRICKS_TELEMETRY_DISABLED` to one
-   of `1`, `true`, `yes`, or `on` (case-insensitive). Other values
-   (empty, `0`, `false`, `off`, `no`) are ignored, leaving the runtime
-   config in charge.
-2. **Programmatic** — pass `telemetryEnabled: false` to `connect()`:
-   ```javascript
-   await client.connect({
-     host,
-     path,
-     token,
-     telemetryEnabled: false,
-   });
-   ```
-3. **Server-side** — Databricks-managed feature flag; if disabled for
-   your workspace, the driver does not emit telemetry regardless of
-   client config.
-
-### Tuning
-
-If you keep telemetry on, the following knobs are available on
-`ConnectionOptions` (see JSDoc on `IDBSQLClient.ts` for defaults and
-units):
-
-- `telemetryAuthenticatedExport` — set to `false` to ship reduced
-  payloads (no statement/session correlation IDs, generic User-Agent)
-  via the unauthenticated endpoint.
-- `telemetryBatchSize`, `telemetryFlushIntervalMs`, `telemetryMaxRetries`
-  — batching and retry tuning.
-- `telemetryCircuitBreakerThreshold`, `telemetryCircuitBreakerTimeout` —
-  circuit-breaker tuning for the export endpoint.
-- `telemetryCloseTimeoutMs` — bound on `await client.close()` waiting for
-  the final flush.
-
-> **Note for short-lived processes**: always `await client.close()`
-> before `process.exit(0)` so the final batch is flushed. Without an
-> explicit close, the periodic flush timer is `unref()`'d to avoid
-> holding the event loop open, so any unflushed events are dropped.
+The Databricks SQL Driver for Node.js includes an **opt-in telemetry system** that collects driver usage metrics and performance data to help improve the driver. Telemetry is **disabled by default** and follows a **privacy-first design**.
+
+### Key Features
+
+- **Privacy-first**: No SQL queries, results, or sensitive data is ever collected
+- **Opt-in**: Controlled by server-side feature flag (disabled by default)
+- **Non-blocking**: All telemetry operations are asynchronous and never impact your queries
+- **Resilient**: Circuit breaker protection prevents telemetry failures from affecting your application
+
+### What Data is Collected?
+
+When enabled, the driver collects:
+
+- ✅ Driver version and configuration settings
+- ✅ Query performance metrics (latency, chunk counts, bytes downloaded)
+- ✅ Error types and status codes
+- ✅ Feature usage (CloudFetch, Arrow format, compression)
+
+**Never collected**:
+
+- ❌ SQL query text
+- ❌ Query results or data values
+- ❌ Table/column names or schema information
+- ❌ User credentials or personal information
+
+### Configuration
+
+To enable or disable telemetry explicitly:
+
+```javascript
+const client = new DBSQLClient({
+  telemetryEnabled: true, // Enable telemetry (default: false)
+});
+
+// Or override per connection:
+await client.connect({
+  host: '********.databricks.com',
+  path: '/sql/2.0/warehouses/****************',
+  token: 'dapi********************************',
+  telemetryEnabled: false, // Disable for this connection
+});
+```
+
+For detailed documentation including configuration options, event types, troubleshooting, and privacy details, see [docs/TELEMETRY.md](docs/TELEMETRY.md).
 
 ## Run Tests