sql-preview 0.5.11 → 0.6.2

package/Changelog.md

@@ -0,0 +1,302 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.6.2] - 2026-06-03
+
+### Added
+
+- Added a product strategy note on using SQL Preview's query wedge to accelerate toward a broader agentic query layer.
+- Added the initial RFC-054 Zed MCP extension scaffold, local verification script, and setup guide.
+- Added Zed marketplace readiness checks, CI, and publishing instructions for submitting the SQL Preview MCP extension to `zed-industries/extensions`.
+- Added Snowflake Browser SSO profile support for VS Code by passing `EXTERNALBROWSER` auth options to the Snowflake driver without storing a Snowflake password.
+
+### Fixed
+
+- Added Snowflake SDK optional-dependency handling so packaged VS Code installs surface guided installation advice instead of an unexplained missing-module failure.
+
+## [0.6.1] - 2026-05-29
+
+### Fixed
+
+- Moved the welcome guide into the SQL Preview panel instead of opening a separate editor tab.
+- Routed connection management actions to Settings > Connections instead of opening the raw daemon localhost URL.
+- Fixed welcome guide connection summary state so existing active profiles are detected.
+- Replaced raw "Session not found" query failures with clear rerun guidance when the daemon restarts during an in-flight query.
+- Fixed settings refresh so a missing telemetry preference keeps the 0.6.1 default enabled state instead of clearing the checkbox.
+- Removed the inactive "Start using SQL Preview" welcome action.
+
+### Changed
+
+- Reworked the welcome guide into a reusable guide hub with multi-database, VS Code/Cursor, MCP, first-query, and latest-highlight sections.
+- Added a Settings > About action to reopen the welcome guide at any time.
+- Added Markdown export for the welcome guide and exposed the same guide as an MCP Markdown resource for agents.
+- Switched SQL Preview product telemetry to enabled by default when VS Code telemetry is enabled, with opt-out available in Settings.
+
+## [0.6.0] - 2026-05-28
+
+### Added
+
+- Added RFC-017 daemon configuration loading with strict JSON defaults, file/env/CLI precedence, validation, source reporting, and a read-only `/config` endpoint.
+- Added documentation and RFC agent guidance for docs stewardship, in-progress RFC tracking, and RFC-to-code commit traceability.
+- Added explicit VS Code active connection selection so users can choose which saved profile runs `.sql` queries.
+- Added PostHog-backed product telemetry plumbing with VS Code telemetry gating, schema validation, safe query buckets, and transparency metadata.
+- Added a General settings telemetry control so users can enable or opt out from the SQL Preview panel.
+- Added RFC-048 query operation contracts with structured MCP results for query execution and tab page retrieval.
+- Added multi-surface tab projection so daemon result tabs can be rendered across VS Code and the browser without session/tab ID collisions.
+- Added RFC-047 daemon surface composition docs and `/status` surface diagnostics for HTTP, MCP HTTP, WebSocket, IPC socket, and stdio readiness.
+- Added package-owned connector descriptors for built-in connector metadata, lazy factories, and dynamic connection form schemas.
+- Added RFC-052 welcome UX and connector migration planning, plus RFC-053 agent skills integration planning.
+- Added the RFC-052 welcome guide with legacy settings migration, migrated-profile connection testing, and explicit telemetry opt-in.
+
+### Fixed
+
+- Made daemon PID-file cleanup verify an existing process via `/status` before terminating it, avoiding unsafe PID reuse kills.
+- Applied the same safe PID verification to the extension daemon client before it terminates stale daemon PIDs.
+- Hardened daemon subprocess connector cleanup with early close/error listeners, bounded stderr capture, abort escalation, and child cleanup for connection tests.
+- Closed stale daemon HTTP MCP sessions instead of only dropping map entries, and included them in resource-change broadcasts.
+- Aborted direct daemon HTTP query execution when clients disconnect before a response is sent.
+- Redacted sensitive MCP request headers in daemon logs while preserving non-secret diagnostics.
+- Added WebSocket MCP message-size enforcement and BigInt-safe serialization to match daemon socket transport behavior.
+- Enforced daemon per-session tab limits during query execution to prevent unbounded result tab growth.
+- Hardened daemon tab/query lifecycle cleanup so closed or reused tabs abort stale queries and cannot lose newer abort controllers.
+- Enforced daemon query timeouts so long-running connector calls receive an abort signal and report a clear timeout error.
+- Bundled the WebSocket runtime into daemon builds so packaged VS Code installs can start `out/server/standalone.js` without relying on an excluded `node_modules/ws` dependency.
+- Fixed Trino connection tests from the Connections panel so they use the same saved credentials and Basic Auth path as normal query execution.
+- Improved Connections panel test-result visibility by wrapping full error details instead of truncating them inline.
+- Fixed ambiguous multi-profile query routing by honoring `sqlPreview.activeConnectionId` before falling back to connector type or list order.
+- Fixed connection password commands so they target the active/selected connection instead of silently updating the first saved profile.
+- Fixed unsaved Trino connection tests so form-entered passwords produce the required Basic Auth header.
+
+### Changed
+
+- Updated the RFC process to include an `inprogress` lifecycle folder and implementation tracking expectations.
+- Routed MCP, VS Code, and browser query execution through a shared daemon query operation lifecycle.
+- Refactored daemon HTTP, MCP Streamable HTTP, WebSocket MCP, IPC socket MCP, and stdio MCP wiring into explicit `src/server/surfaces/` modules.
+- The Connections panel now shows per-connection password status and native Set/Clear actions without exposing stored secrets to the webview.
+- Reorganized the MCP Server settings tool list into clearer grouped sections with short descriptions.
+- The browser session sidebar now filters the shared results layout and routes tab close, cancel, select, and rerun actions through session-aware daemon APIs.
+
+## [0.5.12] - 2026-02-19
+
+### Added
+
+- **Modular Connection Profiles**: Implemented a robust connection management system supporting multiple profile stores (File, Environment Variables) and secure credential handling.
+- **Environment Configuration**: Added support for configuring connections via `SQL_PREVIEW_CONNECTIONS` environment variable.
+- **Profile Management**: Updated Daemon to serve as the single source of truth for connection profiles.
+
+### Fixed
+
+- **Connection Listing**: Fixed `list_connections` tool to correctly return full profile details (excluding passwords) ensuring the extension can execute queries reliably.
+
+## [0.5.11] - 2026-02-16
+
+### Fixed
+
+- **MCP Connection**: Resolved issues with MCP server startup and connection handling.
+- **Testing**: Fixed failing unit and integration tests.
+
+## [0.5.1] - 2026-02-04
+
+### Added
+
+- **Version Checking**: Added automated version checking for extension updates.
+- **Testing**: Added comprehensive unit tests for `ResultsViewProvider`'s version check and webview message handling.
+
+## [0.5.0] - 2026-01-30
+
+### Architecture
+
+- **Daemon Process**: Introduced a standalone `Daemon` service to decouple query execution and state management from the VS Code extension host. This improves stability and enables persistent sessions.
+- **MCP Server Refactor**: Completely rewrote the MCP Server (`DaemonMcpServer`) to run within the Daemon, providing robust tool management and better integration with LLM agents.
+
+### Added
+
+- **RFC Documentation**: Added RFCs 000-005 covering Roadmap, Agentic Testing, Single Server Architecture, MCP UI, and Session Security.
+- **Comprehensive Testing**: Added extensive unit and integration tests (~9.5k lines changed) covering Daemon, MCP, ConnectionManager, and Query execution.
+- **Session Management**: Implemented `SessionManager` and `DaemonClient` for robust state handling across extension reloads.
+
+### Changed
+
+- **Query Execution**: Refactored `QueryExecutor` to support distinct execution modes and better error handling.
+- **Repository**: Renamed repository to `sql-preview` and updated all internal references.
+
+## [0.4.2] - 2026-01-27
+
+### Added
+
+- **Filter Improvements**: Added a "Select All" checkbox to the column set filter, enabling easier bulk selection and deselection of visible items.
+
+### Fixed
+
+- **Data Parsing Integrity**: Fixed a critical issue where high-precision decimal numbers (e.g. `1932.53...`) were incorrectly parsed as "Invalid Number" or strings. The parser now intelligently handles BigInts while preserving standard floating point numbers for correct display and sorting.
+
+## [0.3.9] - Unreleased
+
+### Added
+
+- **Open Source Preparation**:
+  - Added MIT License and updated copyright year to 2026.
+  - Added Security Policy (`SECURITY.md`) and Code of Conduct (`CODE_OF_CONDUCT.md`).
+  - Created Contribution Guidelines (`CONTRIBUTING.md`) and Developer Guide (`ARCHITECTURE.md`).
+  - Added GitHub Issue and Pull Request templates.
+  - configured GitHub Actions for CI/CD (lint, test, build).
+  - Added Dependabot configuration.
+- **Testing & Quality**:
+  - Added `test:coverage` script for test coverage reporting.
+  - Improved unit test reliability (password management tests).
+  - Adopted strict linting and formatting standards.
+- **Codebase**:
+  - Replaced console logs with structured `Logger` in MCP Server.
+  - Cleaned up unused dependencies (`body-parser`, `glob`, etc.).
+
+## [0.3.8] - 2026-01-20
+
+### Added
+
+- **UI UX Polish**:
+  - Implemented "native-like" grid selection feel by removing browser text overlay.
+  - Enhanced copy/paste functionality to reliably copy rows as TSV with headers.
+  - Added persistence for "Row Height" preference (Normal, Compact, Comfortable).
+  - Unified gutter selection styling for a consistent visual experience.
+
+### Changed
+
+- **Architecture**: Decoupled MCP Server from `ResultsViewProvider` for better modularity and stability.
+- **MCP Server**: Improved robustness of server startup/shutdown to prevent `EADDRINUSE` and `ERR_SERVER_NOT_RUNNING` errors.
+
+### Fixed
+
+- **Runtime Stability**: Resolved race conditions in MCP server lifecycle.
+- **Styling**: Fixed AG Grid focus ring issues and selection color inconsistencies.
+
+## [0.2.4] - 2026-01-12
+
+### Fixed
+
+- **State Persistence**: Resolved persistent test failures and ensured `workspaceState` is correctly managed.
+- **Results Provider**: Fixed memory leaks by cleaning up event listeners on disposal.
+- **Linting**: Addressed numerous code style and type safety issues (removed console logs, fixed strict types).
+
+## [0.2.2] - 2025-12-08
+
+### Added
+
+- **Tab Naming Configuration**: Added `sqlPreview.tabNaming` setting to switch between `file-sequential` (Result 1, Result 2) and `query-snippet` naming.
+- **Settings Organization**: Organized settings into transparent groups: Connection, Display, and Advanced (Beta).
+
+### Fixed
+
+- **Tab Naming**: Fixed issue where tabs would revert to query snippet naming during loading.
+- **Loading UX**: Improved loading experience by hiding the empty grid and random headers while the query executes.
+
+## [0.2.1] - 2025-12-01
+
+### Added
+
+- **MCP Server**: Added Model Context Protocol (MCP) server feature for enhanced context awareness.
+
+### Fixed
+
+- **Persistence**: Fixed issues with state persistence.
+- **Tab Management**: Fixed tab focus issues and added comprehensive tests for tab management.
+- **Sync**: Fixed MCP synchronization issues.
+
+## [0.2.0] - 2025-11-30
+
+### Added
+
+- **AG Grid Improvements**:
+  - Added copy functionality for rows, columns, and cells.
+  - Added query tooltips.
+  - Added column datatypes display in headers.
+- **Run in New Tab**: Added capability to execute queries in a new tab.
+- **JSON Viewer**: Added a JSON viewer for better data inspection.
+
+### Changed
+
+- **AG Grid Standardization**:
+  - Restored standard column menu.
+  - Enhanced context menu.
+  - Updated scrollbar styling.
+- **Refactor**: Moved column type display to tooltips and fixed selection behavior.
+
+### Fixed
+
+- **Windows Compatibility**: Addressed further Windows-specific bugs.
+- **Network**: Fixed HTTPS request handling.
+
+## [0.1.6] - 2025-11-07
+
+### Fixed
+
+- Work around Porta returning "Empty query not supported" for valid SQL when using the Trino client. The extension now executes the first page via direct HTTPS POST to `/v1/statement` with Trino and Presto headers, then follows `nextUri` using HTTP GET. This mirrors clients like DataGrip and restores compatibility.
+- Pagination: continue even when `columns` are not present in the first response (some clusters send columns on later pages).
+- Export flow aligned to the same direct POST + pagination path for consistency.
+
+### Added
+
+- Probes to diagnose connectivity quickly:
+  - `npm run probe` (multiple HTTP variants)
+  - `npm run probe:extension` (matches extension path end-to-end)
+- `.env.local` workflow (git-ignored) and `env.example` for credentials during local probes.
+
+### Added
+
+- Initial VS Code extension setup for Presto/Trino database connections
+- **Secure password storage** using VS Code's SecretStorage API
+- Password management commands for secure credential handling
+- **Settings UI integration** for password management with "Set Password" button
+- Command palette integration with `Presto: Run Query` command
+- Code lens provider for executing SQL queries directly from editor
+- Results view panel with Tabulator integration for data visualization
+- Configuration setting for maximum rows to display (`presto.maxRowsToDisplay`)
+- Pagination support for fetching large result sets
+- Visual styling improvements for the results grid:
+  - Integration with VS Code theme
+  - Row number column
+  - Improved formatting and density
+  - Header styling enhancements
+- Connection handling with authentication support
+- Error handling and display in the results view
+- Query execution status indicators
+- Dynamic theme color integration with VS Code:
+  - Table adapts to user's selected theme
+  - Row backgrounds, text colors, and borders match theme
+  - Support for light, dark, and high-contrast themes
+  - Live theme updates when user changes VS Code theme
+
+### Changed
+
+- **SECURITY**: Removed plaintext password storage from settings - now uses secure VS Code SecretStorage
+- Replaced Tabulator with AG Grid for the results view, providing enhanced features and a more modern grid experience.
+- Enabled floating filters by default in the AG Grid results view for easier column-specific filtering.
+- Updated results display to use Tabulator for better data visualization
+- Improved results panel styling to better match VS Code themes
+- Enhanced query result handling with pagination support
+- Switched from `client.execute()` to `client.query()` for compatibility
+- Refactored CSS to use theme variables for consistent styling
+
+### Fixed
+
+- **Windows Compatibility**: Fixed "path must not be empty" error during extension activation on Windows systems
+  - Added comprehensive path validation and normalization for cross-platform compatibility
+  - Enhanced webview resource path handling with graceful fallback mechanisms
+  - Implemented proper error handling and logging for path-related issues
+  - Added validation for extension URI and resource roots to prevent empty path errors
+  - Improved extension activation robustness with detailed error reporting
+  - Properly mocked filesystem dependencies in tests instead of bypassing validation
+- Resolved pagination issues when fetching large result sets
+- Fixed layout and styling issues in the results view
+- Corrected variable declarations (let vs const) based on usage patterns
+- Addressed linter errors and warnings
+- Fixed module resolution for the Results View Provider
+- Resolved connection and authentication issues with Trino client
+
+### Developer Improvements
+
+- Added ESLint configuration
+- Configured TypeScript compilation settings
+- Added proper module structure and organization
+- Implemented better error handling and logging
+- Created theme-aware UI components for improved user experience

package/README.md

@@ -1,106 +1,257 @@
-# SQL Preview for VS Code
+# SQL Preview
 
-A Visual Studio Code extension for connecting to **Trino** databases, running SQL queries, and visualizing results directly within your editor.
+**A fast SQL workspace for VS Code and MCP-enabled AI agents.**
 
-## Features
+Run SQL in VS Code, manage database profiles securely, inspect results in a
+high-performance grid, and expose governed database tools to Claude, Cursor,
+Copilot, and other Model Context Protocol clients.
 
-- **SQL Query Execution**: Run SQL queries against Trino databases directly from VS Code.
-- **Interactive Results View**: View query results in a high-performance AG Grid table with sorting, filtering, and resizing.
-- **Code Lens Integration**: Execute queries with a single click from your `.sql` files.
-- **Client-Server Architecture**: Uses a dedicated background daemon for reliable connection management and query execution.
-- **Secure Password Storage**: Passwords are encrypted using the OS keyring via VS Code's SecretStorage API.
-- **MCP Integration (Beta)**: Exposes database tools to AI agents via the Model Context Protocol.
+[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/mehul.sql-preview?label=VS%20Code%20Marketplace&color=0066b8)](https://marketplace.visualstudio.com/items?itemName=mehul.sql-preview)
+[![Installs](https://img.shields.io/visual-studio-marketplace/i/mehul.sql-preview)](https://marketplace.visualstudio.com/items?itemName=mehul.sql-preview)
+[![OpenVSX](https://img.shields.io/open-vsx/v/mehul/sql-preview?label=OpenVSX&color=a60ee5)](https://open-vsx.org/extension/mehul/sql-preview)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-## Usage
+---
 
-### Running Queries
+## Why SQL Preview?
 
-1.  Open a `.sql` file.
-2.  **Code Lens**: Click "Run Query" above the SQL block.
-3.  **Command Palette**: Open the palette (`Cmd+Shift+P`) and run `SQL Preview: Run Query`.
-4.  **Shortcut**: Press `Cmd+Enter` (Mac) or `Ctrl+Enter` (Windows/Linux) to run the query.
+SQL Preview is built for the workflow where humans and agents both need real
+database context:
 
-### Viewing Results
+- **Query from the editor**: open a `.sql` file, press `Cmd+Enter` or
+  `Ctrl+Enter`, and inspect results without leaving VS Code.
+- **Manage real connection profiles**: create, test, select, and migrate
+  database connections from the SQL Preview panel.
+- **Give agents governed access**: expose read-only MCP tools for running
+  queries, listing schemas and tables, describing columns, and inspecting shared
+  result tabs.
+- **Stay local-first**: there is no hosted SQL Preview service and no bundled
+  AI model. Credentials stay in your VS Code Secret Storage or your local
+  daemon profile configuration.
 
-Results appear in the **SQL Preview** panel.
+---
 
-- **Sort**: Click column headers.
-- **Filter**: Use the text boxes below headers.
-- **Export**: Right-click to copy cells.
+## Highlights
 
-## Architecture
+- **Connection manager** with dynamic connector forms, active profile selection,
+  legacy settings migration, and per-connection password actions.
+- **Tabbed result grid** powered by AG Grid with sorting, filtering, column type
+  display, adjustable density, TSV copy, and full CSV export.
+- **Daemon-backed execution** so heavy queries do not block the editor and
+  results can be shared across VS Code, browser, and MCP surfaces.
+- **MCP server** for Claude Desktop, Cursor, Copilot, and other MCP clients,
+  with safe mode enabled by default for read-only operation.
+- **Multi-surface sessions** so agent-triggered and editor-triggered work can be
+  inspected through the same local daemon without tab ID collisions.
+- **Transparent telemetry** that is off by default, opt-in only, and never sends
+  SQL text, results, credentials, hostnames, database names, schema/table/column
+  names, file paths, usernames, or raw errors.
 
-This extension uses a robust **Client-Server** model:
+---
 
-1.  **Extension (Client)**: The VS Code frontend that handles UI, commands, and configuration.
-2.  **Daemon (Server)**: A separate Node.js process that manages database connections and executes queries.
-3.  **Communication**: The Client and Daemon communicate via the **Model Context Protocol (MCP)** over local sockets.
+## Supported Databases
 
-This separation ensures that long-running queries do not block the VS Code UI and provides a stable environment for database interactions.
+SQL Preview ships connector metadata and setup forms for:
 
-## Configuration
+| Database       | Connector   |
+| -------------- | ----------- |
+| PostgreSQL     | `postgres`  |
+| MySQL          | `mysql`     |
+| SQLite         | `sqlite`    |
+| DuckDB         | `duckdb`    |
+| Trino / Presto | `trino`     |
+| Snowflake      | `snowflake` |
+| BigQuery       | `bigquery`  |
+| SQL Server     | `mssql`     |
+
+Trino/Presto and PostgreSQL are bundled into the extension build. Native and
+cloud-provider connectors are lazy-loaded and may require their driver runtime in
+the active environment; SQL Preview reports guided missing-driver errors instead
+of failing silently.
+
+---
+
+## Quick Start: VS Code
+
+1. Install SQL Preview from the
+   [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=mehul.sql-preview)
+   or [OpenVSX](https://open-vsx.org/extension/mehul/sql-preview).
+2. Run **SQL Preview: Manage Connections** from the Command Palette.
+3. Add a connection profile, set its password, test it, and make it active.
+4. Open a `.sql` file and press **`Cmd+Enter`** on macOS or **`Ctrl+Enter`** on
+   Windows/Linux.
+
+Results open in the **SQL Preview** panel at the bottom of the editor. To force a
+new tab, run **SQL Preview: Run Query (+ Tab)**.
+
+### Migrating from Legacy Settings
+
+If you previously configured `sqlPreview.host`, `sqlPreview.port`,
+`sqlPreview.user`, `sqlPreview.catalog`, `sqlPreview.schema`, or
+`sqlPreview.databasePath`, open **SQL Preview: Show Welcome Guide** or
+**SQL Preview: Manage Connections**. SQL Preview can import those settings into a
+named connection profile and keep passwords in VS Code Secret Storage.
+
+---
 
-Add the following configuration to your `settings.json`:
+## Quick Start: MCP Agents
+
+### From VS Code
+
+1. Run **SQL Preview: Manage Connections** and confirm your active connection.
+2. Open the SQL Preview settings panel and enable the MCP server.
+3. Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
+4. Configure HTTP-capable MCP clients with the local endpoint shown in the panel,
+   typically:
 
 ```json
 {
-  "sqlPreview.defaultConnector": "trino",
-  "sqlPreview.host": "trino-coordinator.example.com",
-  "sqlPreview.port": 443,
-  "sqlPreview.user": "your-username",
-  "sqlPreview.catalog": "hive",
-  "sqlPreview.schema": "default",
-  "sqlPreview.ssl": true,
-  "sqlPreview.sslVerify": true,
-  "sqlPreview.maxRowsToDisplay": 1000,
-  "sqlPreview.logLevel": "INFO" // Options: DEBUG, INFO, WARN, ERROR
+  "mcpServers": {
+    "sql-preview": {
+      "url": "http://localhost:8414/mcp"
+    }
+  }
 }
 ```
 
-### Secure Password Management
+You can also open the Extensions view, search `@mcp SQL Preview`, and install
+the server into your user profile or current workspace from the MCP gallery.
+
+### Standalone Server
 
-For security, passwords are never stored in plain text.
+For Claude Desktop, Cursor, CI jobs, or any headless MCP client, use the
+standalone server:
+
+```json
+{
+  "mcpServers": {
+    "sql-preview": {
+      "command": "npx",
+      "args": ["-y", "sql-preview", "--stdio"],
+      "env": {
+        "SQL_PREVIEW_CONNECTIONS": "[{\"id\":\"analytics\",\"name\":\"Analytics\",\"type\":\"postgres\",\"host\":\"localhost\",\"port\":5432,\"user\":\"analyst\",\"database\":\"warehouse\",\"password\":\"YOUR_PASSWORD\"}]"
+      }
+    }
+  }
+}
+```
 
-1.  **Set Password**: Run the command `SQL Preview: Set Database Password` or click "Set Password" in the Settings UI.
-2.  **Clear Password**: Run `SQL Preview: Clear Stored Password`.
+The MCP server exposes tools for:
 
-## 🤖 Model Context Protocol (MCP) Integration (Beta)
+| Tool               | What it does                                        |
+| ------------------ | --------------------------------------------------- |
+| `run_query`        | Execute SQL and return typed JSON rows              |
+| `list_connectors`  | Return supported connector types and setup schemas  |
+| `list_connections` | List configured connection profiles without secrets |
+| `save_connection`  | Add or update a connection profile                  |
+| `test_connection`  | Validate saved or unsaved connection settings       |
+| `list_schemas`     | List schemas for a connection                       |
+| `list_tables`      | List tables within a schema                         |
+| `describe_table`   | Return column names and types                       |
+| `get_tab_info`     | Inspect daemon result tab state                     |
+| `cancel_query`     | Cancel a running query                              |
+| `close_tab`        | Close a daemon result tab                           |
 
-This extension includes a built-in MCP server that allows AI assistants (like Claude) to interact with your database.
+Safe mode is on by default and restricts agents to read-only statements such as
+`SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`, and connector-specific metadata
+queries.
 
-### Enabling MCP
+See the full [Claude Desktop setup guide](docs/engineering/guides/claude-desktop-setup.md)
+and [daemon URL reference](docs/engineering/guides/daemon-url-reference.md) for
+advanced configuration.
 
-1.  Open VS Code Settings.
-2.  Set `sqlPreview.mcpEnabled` to `true`.
-3.  (Optional) Set `sqlPreview.mcpSafeMode` to `true` (default) to restrict AI to read-only queries.
-4.  Restart the extension or run `SQL Preview: Restart Background Server`.
+---
 
-### Available Tools
+## Configuration
 
-When enabled, the following tools are available to MCP clients:
+Most users should use **SQL Preview: Manage Connections** instead of editing
+settings JSON by hand.
 
-- `run_query`: Execute a SQL query.
-- `list_tables`: List tables in a schema.
-- `describe_table`: Show table schema.
-- `get_ddl`: Get the CREATE TABLE statement.
+| Setting                         | Default                    | Description                                                |
+| ------------------------------- | -------------------------- | ---------------------------------------------------------- |
+| `sqlPreview.activeConnectionId` | empty                      | Connection profile used for VS Code query execution        |
+| `sqlPreview.maxRowsToDisplay`   | `500`                      | Max rows shown in the grid; full export is still available |
+| `sqlPreview.fontSize`           | `0`                        | Results grid font size in px; `0` inherits from the editor |
+| `sqlPreview.rowHeight`          | `normal`                   | Grid density: `compact`, `normal`, or `comfortable`        |
+| `sqlPreview.tabNaming`          | `file-sequential`          | Result tab naming strategy                                 |
+| `sqlPreview.alwaysRunInNewTab`  | `false`                    | Always open query results in a new tab                     |
+| `sqlPreview.mcpEnabled`         | `false`                    | Enable the local MCP server for agent access               |
+| `sqlPreview.mcpSafeMode`        | `true`                     | Restrict MCP query execution to read-only statements       |
+| `sqlPreview.telemetry.enabled`  | `false`                    | Opt in to anonymous product telemetry                      |
+| `sqlPreview.telemetryHost`      | `https://us.i.posthog.com` | Advanced PostHog-compatible telemetry endpoint             |
 
-## Project Structure
+Legacy connection settings such as `sqlPreview.host`, `sqlPreview.port`,
+`sqlPreview.user`, `sqlPreview.catalog`, `sqlPreview.schema`, and
+`sqlPreview.databasePath` remain available for migration and backward
+compatibility.
 
+### Passwords and Secrets
+
+Passwords entered through the VS Code connection manager are stored per
+connection in VS Code Secret Storage, backed by the operating system keychain.
+They are not written to `settings.json` or sent to the webview.
+
+Use these commands when needed:
+
+- **SQL Preview: Set Connection Password**
+- **SQL Preview: Clear Connection Password**
+- **SQL Preview: Manage Connections**
+
+### Telemetry
+
+SQL Preview telemetry is off by default. If enabled, events are anonymous,
+allowlisted, and used to improve setup, connector reliability, query workflows,
+MCP adoption, and product quality. SQL Preview never sends SQL text, query
+results, credentials, hostnames, database/schema/table/column names, file paths,
+workspace names, usernames, environment variables, process arguments, raw error
+messages, or stack traces.
+
+Use **SQL Preview: Show Telemetry Status** to inspect the effective telemetry
+state.
+
+---
+
+## Architecture
+
+SQL Preview uses a local daemon model:
+
+```text
+VS Code extension / MCP client / browser surface
+        |
+        v
+SQL Preview daemon on localhost
+        |
+        v
+Database connector
+        |
+        v
+Your database
 ```
-sql-preview/
-├── src/
-│   ├── extension.ts          # Main extension entry point (Client)
-│   ├── server/               # Daemon process (Server)
-│   │   ├── Daemon.ts         # Server entry point
-│   │   └── DaemonMcpServer.ts # MCP implementation
-│   ├── connectors/           # Database connectors (Trino)
-│   └── ui/                   # Webview logic
-└── webviews/                 # Frontend assets (React/HTML/CSS)
-```
 
-## Development
+The daemon owns connection profiles, query execution, result tabs, MCP
+transports, and browser/VS Code projections. That lets editor sessions and agent
+sessions share the same local state while keeping credentials and execution on
+your machine.
+
+---
+
+## Release Notes
+
+See [Changelog.md](Changelog.md) for the full release history.
+
+---
+
+## Contributing
+
+Contributions are welcome, especially new connector support, reliability
+improvements, and documentation fixes. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for setup instructions and development workflow.
+
+Found a bug? Open an issue on
+[GitHub](https://github.com/fadnavismehul/sql-preview/issues).
+
+---
+
+## License
 
-1.  **Clone**: `git clone ...`
-2.  **Install**: `npm install`
-3.  **Build**: `npm run build`
-4.  **Debug**: Press `F5` to start the Extension Host.
+MIT (c) 2026 [Mehul Fadnavis](https://github.com/fadnavismehul)