Improve readme files.

CONTRIBUTING.md

@@ -20,6 +20,23 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio
 4. Run tests and ensure the build passes
 5. Submit a pull request
 
+## Repository Structure
+
+| Path | Description |
+|------|-------------|
+| `KustoExplorerVscode.slnx` | Visual Studio solution for the entire extension |
+| `src/Client` | TypeScript VS Code extension (UI, LSP client, extension features) |
+| `src/Server` | C# LSP server (Kusto parser integration, code services) |
+| `src/ServerTests` | C# tests for the server |
+
+### Client
+
+The Client is written in TypeScript and contains the VS Code extension code, including the UI components, LSP client and other extension features that are not dependent on the Kusto parser library.
+
+### Server
+
+The Server is written in C# to interact with the .NET version of the Kusto parser library for better typing performance. It primarily contains LSP handlers and redirects requests to the parser library's code services.
+
 ## Development Setup
 
 ### Prerequisites
@@ -49,19 +66,38 @@ npm run compile
 2. Press `F5` to launch the Extension Development Host
 3. Open a `.kql` file to activate the extension
 
-### Packaging the Extension
+## Debugging
+
+### Debugging the Client
+
+1. Open the `src/Client` folder in VS Code
+2. Build the client using the `compile` task in the **NPM SCRIPTS** explorer panel
+3. Build the server using `build-debug-server` in the same panel
+4. Press **F5** to launch the Extension Development Host with debugging enabled
+
+### Debugging the Server
+
+1. Launch the extension in debug mode (above) — the server starts automatically
+2. Attach to the server process:
+   - **Visual Studio** — open `KustoExplorerVscode.slnx` and attach to the `dotnet.exe` process for the extension
+   - **VS Code** — from the repo root, run `Debug: Attach to a .NET 5+ or .NET Core process` (`Ctrl+Shift+P`) and select the `Server` process
+
+## Packaging
 
 ```bash
+# Requires vsce: npm install -g @vscode/vsce
 cd src/Client
 npm run package
 ```
 
 This will create a `.vsix` file that can be installed in VS Code.
 
-## Project Structure
+### Manual Install / Uninstall
 
-- `src/Server/` - Vs Code extension Server (C#)
-- `src/Client/` - VS Code extension Client (TypeScript)
+```bash
+code --install-extension <vsix-file> [--force]
+code --uninstall-extension ms-kusto.kusto-explorer-vscode
+```
 
 ## Reporting Issues
 

README.md

@@ -1,65 +1,47 @@
-# Kusto Explorer for VS Code
+# Kusto Explorer for VS Code
 
-- Edit, run and chart Kusto queries (KQL)
-- Explore databases and query results
-- Consult copilot to help create, run and diagnose your queries
-- Works just like the Kusto Explorer desktop app and Azure Data Explorer
-- Runs on Windows, Mac and Linux
+[![VS Marketplace](https://img.shields.io/badge/VS%20Marketplace-Kusto%20Explorer-blue?logo=visual-studio-code)](https://marketplace.visualstudio.com/items?itemName=ms-kusto.kusto-explorer-vscode)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-## Downloading and Using the Extension
+Edit, run, and chart Kusto queries (KQL) right from VS Code. Explore databases and results, and use Copilot to help author and diagnose your queries. Works on Windows, macOS, and Linux.
 
-- Install from within VS Code: [Kusto Explorer]
-- Or download VSIX from [GitHub Releases](https://github.com/microsoft/Kusto-Explorer-VsCode/releases)
-- [How to Use the Extension](src/Client/README.md)
+## Features
 
-----
-
-## Using this Repository
-
-- KustoExplorerVscode.slnx - Visual Studio solution file for the entire extension
-- src/Client - TypeScript vscode extension
-- src/Server - C# LSP Server
-- src/ServerTests - C# Tests for the server codebase
-
-### Client
-The Client is written in TypeScript and contains the VS Code extension code, including the UI components, LSP client and other extension features.
-that are not dependent on the Kusto parser library.
-
-### Server
-The Server is written in C# to interact with the dotnet version of the Kusto parser library for better typing performance.
-It primarily contains just LSP handlers and redirects requests to the parser library's code services.
-Some other custom features are also implemented here, but eventually most of these will move out to be handled by the client with the goal of leaving only code service related features in the server codebase.
+- **Query editor** — IntelliSense, formatting, go-to-definition, find references, code actions and quick fixes
+- **Results panel** — browse tabular results, copy cells, drag-and-drop as `datatable` expressions
+- **Charts** — create and customize charts from query results; copy as image or save as `.kqr` files
+- **Database explorer** — browse clusters, databases, tables, functions and more
+- **Copilot integration** — ask Copilot to help create, run and diagnose your queries
+- **Scratch pads** — jot down queries without creating files
+- **Query history** — revisit previously executed queries and results
 
-### Debugging the Client
-1. Open `src\Client` folder in VS Code
-2. Build the client side using `compile` command in explorer panel `NPM SCRIPTS`
-3. Build the server side using `build-debug-server` in explorer panel `NPM SCRIPTS`
-4. Press F5 to launch the extension in a new VS Code window with debugging enabled
+## Install
 
-### Debugging the Server
-1. Run the extension in debug mode as described above, which will also launch the server in debug mode
-2. Attach to the server process using one of the following:
-   - **Visual Studio**: Open `KustoExplorerVscode.slnx` and attach to the dotnet.exe process associated with the extension
-   - **VS Code**: Open the repository root folder, then run command `Debug: Attach to a .NET 5+ or .NET Core process` (Ctrl+Shift+P) and select the `Server` process
+**[Install from the VS Code Marketplace →](https://marketplace.visualstudio.com/items?itemName=ms-kusto.kusto-explorer-vscode)**
 
-### Creating the VSIX installer
+Or search for **"Kusto Explorer"** in the VS Code Extensions view (`Ctrl+Shift+X`).
 
-1. Must have vsce installed (npm install -g @vscode/vsce)
-2. run `npm run package` on command line within `src/Client` folder to build the .vsix file
+Alternatively, download the `.vsix` from [GitHub Releases](https://github.com/microsoft/Kusto-Explorer-VsCode/releases) and install manually:
 
-### Installing the VSIX manually
+```sh
+code --install-extension <vsix-file>
+```
 
-Run `code --install-extension <vsix file> [--force]` on command line.
+## Getting Started
 
-### Uninstalling the extension manually
+For a full walkthrough of the extension's features, see the [User Guide](src/Client/README.md).
 
-Run `code --uninstall-extension Microsoft.kusto-explorer-vscode` on command line.
+1. Open the **Kusto Explorer** icon in the VS Code Activity Bar
+2. Add a cluster connection in the **Connections** sidebar
+3. Select a database to set it as active for your query document
+4. Write a query (or ask Copilot for help), then press **F5** to run it
+5. View results in the bottom panel — add a chart, copy data, or save as `.kqr`
 
 ----
 
 ## Contributing
 
-This project welcomes contributions and suggestions. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+This project welcomes contributions and suggestions. For development setup, debugging, and build instructions, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or

src/Client/README.md

@@ -1,63 +1,74 @@
 # Kusto Explorer (VS Code Extension)
 
-- Edit, run and chart Kusto queries (KQL)
-- Explore databases and query results
-- Consult copilot to help create, run and diagnose your queries
+Edit, run, and chart Kusto queries (KQL) right from VS Code. Explore databases and results, and use Copilot to help author and diagnose your queries. Works on Windows, macOS, and Linux.
 
 ## Get Started
-- Select the Kusto Explorer icon in VS Code activity panel
-- Select a scratch pad document, or open/create a `.kql` file
-- Connect the query document to a Kusto cluster and database (if not already connected)
-	- Add a cluster connection in the *Connections* sidebar (if it does not yet exist)
-	- Select a database (below cluster item) to set the active cluster and database for the document
-- Write a Kusto query or consult copilot for help writing one
-- Press F5 to execute the query and view results in the results panel
-- Use the chart button in the results panel to create a chart for your result data
-- Edit the chart options to customize the chart type, axes, legend and more
-- Add another query to the document or edit the prior one, and run it too
-- Revisit prior results in the *History* sidebar
-
-## Connections (sidebar)
-- Keep a list of Kusto clusters you use to run queries
-- Select a cluster and database to be the defaults for your active query document
-- Explore the entities (tables, functions, etc) contained in each database
-
-## Scratch Pads (sidebar)
-- Scratch pad documents for jotting down queries without needing to create and name a file
-
-## History (sidebar)
- - Previously executed queries and their results that you can revisit
-
-## Query Editor (query set documents)
+
+1. Select the **Kusto Explorer** icon in the VS Code Activity Bar
+2. Open a scratch pad or create a `.kql` file
+3. Connect to a Kusto cluster and database:
+   - Add a cluster connection in the **Connections** sidebar (if it doesn't exist yet)
+   - Select a database to set the active cluster and database for the document
+4. Write a Kusto query (or ask Copilot for help)
+5. Press **F5** to execute the query and view results in the Results panel
+6. Use the chart button to visualize your results — customize chart type, axes, legend, and more
+7. Revisit prior queries and results in the **History** sidebar
+
+## Features
+
+### Query Editor
+
 - Edit queries like a source code document
 - Multiple independent queries in a single document, separated by a blank line
-- Intellisense (auto completions, hover tips)
+- IntelliSense (auto-completions, hover tips)
 - Formatting (pretty printing)
-- Goto definition and find all references for tables, functions, columns and more
+- Go-to-definition and find-all-references for tables, functions, columns, and more
 - Code actions and quick fixes for common issues and refactorings
 - Copy colorized query text to the clipboard for pasting into other documents
 
-## Results Panel (bottom panel)
-- Copy contents of cells or entire table to clipboard
+### Connections (sidebar)
+
+- Maintain a list of Kusto clusters you connect to
+- Select a cluster and database to set the defaults for your active query document
+- Explore database entities — tables, functions, materialized views, and more
+
+### Scratch Pads (sidebar)
+
+- Scratch pad documents for jotting down queries without creating and naming a file
+
+### History (sidebar)
+
+- Browse previously executed queries and their results
+- Re-open past results without re-running the query
+
+### Results Panel (bottom panel)
+
+- Copy cell contents or entire tables to the clipboard
 - Drag and drop a table into your document as a KQL `datatable` expression
-- Add a chart to the results or edit the one you have to customize the chart type, axes, legend and more
-- Save the data as a `.kqr` file (Kusto Query Results) to share with others
+- Add or edit a chart to visualize your results
+- Save data as a `.kqr` file (Kusto Query Results) to share with others
+
+### Charts (document tab)
+
+- Create and customize charts — choose chart type, axes, legend, and more
+- Copy the chart as an image (light-mode or dark-mode) to the clipboard
+- Save chart and data together as a `.kqr` file
 
-## Chart Panel (document tab)
-- Edit the chart options to customize the chart type, axes, legend and more
-- Copy the chart as an image to clipboard for either light-mode or dark-mode pasting
-- Save chart and data as a `.kqr` file (Kusto Query Result)
+### Results Viewer (document tab)
 
-## Results Viewer (document tab)
-- View saved `.kqr` files (chart, data and query in one view panel)
-- Add a chart if you don't have one yet
-- Edit the chart options to customize the chart type, axes, legend and more
-- Copy the chart as an image to clipboard for either light-mode or dark-mode pasting
-- Copy the data to clipboard just like results panel
+- Open saved `.kqr` files — chart, data, and query in a single view
+- Add or edit charts, copy data, and export images just like the Results panel
+
+### Copilot Integration
+
+- Ask Copilot to help write, run, and diagnose your Kusto queries
 
 ## Requirements
-- VS Code 1.9.0 or higher
 
-## Repository
-- To file issues, explore the sources or contribute: 
- [[GitHub Repository]](https://github.com/microsoft/Kusto-Explorer-VsCode) 
+- VS Code 1.90.0 or higher
+
+## Links
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-kusto.kusto-explorer-vscode) — install the extension
+- [GitHub Repository](https://github.com/microsoft/Kusto-Explorer-VsCode) — source code, issues, and contributions
+- [KQL Reference](https://learn.microsoft.com/en-us/kusto/query/) — Kusto Query Language documentation