docs: enhance README documentation with Quick Start, Features, and Development sections

jpoehnelt · jpoehnelt · commit aa37b9e5686d · 2025-10-08T22:11:23.000-07:00
diff --git a/.changeset/polite-turkeys-hear.md b/.changeset/polite-turkeys-hear.md
@@ -0,0 +1,15 @@
+---
+"google-workspace-developer-tools": patch
+---
+
+Significantly improved README documentation for both the monorepo and VS Code extension:
+
+- Added comprehensive Quick Start section with multiple installation methods
+- Enhanced Features section with detailed OAuth2 scope intelligence capabilities
+- Included visual scope classification indicators (Restricted, Sensitive, Non-Sensitive)
+- Added "How It Works" section explaining extension functionality
+- Expanded usage instructions with code examples
+- Added Development section with setup commands and project structure
+- Included Resources section with links to Google Workspace documentation
+- Improved overall organization, readability, and visual hierarchy with emoji icons
+- Added marketplace badges and better formatting throughout
diff --git a/README.md b/README.md
@@ -1,15 +1,117 @@
-# Google Workspace Developer Tools Monorepo
+# Google Workspace Developer Tools
 
-This repository is a monorepo for tools that help Google Workspace developers.
+[![Build Status](https://github.com/googleworkspace/developer-tools/actions/workflows/test.yml/badge.svg)](https://github.com/googleworkspace/developer-tools/actions/workflows/test.yml)
+[![Release Status](https://github.com/googleworkspace/developer-tools/actions/workflows/release.yml/badge.svg)](https://github.com/googleworkspace/developer-tools/actions/workflows/release.yml)
+[![Apache 2.0 License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Packages
+A collection of developer tools to enhance your Google Workspace development experience. This monorepo contains extensions, utilities, and resources designed to streamline development workflows for Google Workspace APIs and integrations.
 
-- [`packages/vscode-extension`](./packages/vscode-extension): A VS Code extension with tools to help Google Workspace developers available at [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=google-workspace.google-workspace-developer-tools) and [Open VSX Registry](https://open-vsx.org/extension/google-workspace/google-workspace-developer-tools).
+## 🚀 Quick Start
 
-### With the Gemini CLI
+### VS Code Extension
 
-If you have the `gemini` command-line tool installed, you can install the extension with this command:
+Get intelligent OAuth2 scope linting and enhanced development tools directly in your editor:
+
+**Install from Visual Studio Code:**
+
+1. Open the Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X`)
+2. Search for "Google Workspace Developer Tools"
+3. Click Install
+
+**Or install via command line:**
+
+```sh
+code --install-extension google-workspace.google-workspace-developer-tools
+```
+
+**Marketplaces:**
+
+- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=google-workspace.google-workspace-developer-tools)
+- [Open VSX Registry](https://open-vsx.org/extension/google-workspace/google-workspace-developer-tools)
+
+### Gemini CLI Extension
+
+If you have the `gemini` command-line tool installed:
+
+```sh
+gemini extensions install \
+  "https://github.com/googleworkspace/developer-tools"
+```
+
+## 📦 Packages
+
+### VS Code Extension (`packages/vscode-extension`)
+
+A comprehensive VS Code extension providing:
+
+- **OAuth2 Scope Linting**: Automatic warnings and suggestions for Google Workspace OAuth2 scopes in your code
+  - Validates scope URLs against the official Google API registry
+  - Highlights restricted and sensitive scopes
+  - Provides hover documentation with scope descriptions and API associations
+- **MCP (Model Context Protocol) Server**: Integrated support for enhanced AI-powered development tools
+
+[Learn more →](./packages/vscode-extension)
+
+## 🛠️ Development
+
+This is a monorepo managed with [pnpm](https://pnpm.io/) and [Turbo](https://turbo.build/).
+
+### Prerequisites
+
+- Node.js (v18 or later recommended)
+- pnpm (`npm install -g pnpm`)
+
+### Setup
 
 ```sh
-gemini extensions install "https://github.com/googleworkspace/developer-tools"
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run tests
+pnpm test
+
+# Lint and format code
+pnpm lint
+
+# Watch mode for development
+pnpm --filter google-workspace-developer-tools dev
 ```
+
+### Project Structure
+
+```
+├── packages/
+│   └── vscode-extension/     # VS Code extension
+├── turbo.json                # Turbo build configuration
+└── pnpm-workspace.yaml       # pnpm workspace configuration
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's bug reports, feature requests, or code contributions, please check out our [contributing guidelines](CONTRIBUTING.md) to get started.
+
+### Ways to Contribute
+
+- 🐛 Report bugs and issues
+- 💡 Suggest new features or improvements
+- 📝 Improve documentation
+- 🔧 Submit pull requests
+
+## 💬 Support
+
+If you have questions or encounter issues:
+
+- 📋 [File an issue](https://github.com/googleworkspace/developer-tools/issues) on GitHub
+- 💡 Check existing issues for solutions
+- 📚 Review the documentation in each package
+
+## 📄 License
+
+This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.
+
+---
+
+Made with ❤️ for the Google Workspace developer community
diff --git a/packages/vscode-extension/README.md b/packages/vscode-extension/README.md
@@ -1,43 +1,136 @@
 # Google Workspace Developer Tools
 
-This VS Code extension provides a set of tools to help Google Workspace developers.
+[![Visual Studio Marketplace](https://img.shields.io/visual-studio-marketplace/v/google-workspace.google-workspace-developer-tools?label=VS%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=google-workspace.google-workspace-developer-tools)
+[![Open VSX](https://img.shields.io/open-vsx/v/google-workspace/google-workspace-developer-tools?label=Open%20VSX)](https://open-vsx.org/extension/google-workspace/google-workspace-developer-tools)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Features
+Enhance your Google Workspace development experience with intelligent OAuth2 scope linting, hover documentation, and AI-powered development tools directly in Visual Studio Code.
 
-- **OAuth2 Scope Linting**: Get warnings and additional information for Google Workspace [OAuth2 scopes](https://developers.google.com/identity/protocols/oauth2/scopes) in your code.
+## ✨ Features
 
-  ![OAuth2 Scope Linting](https://raw.githubusercontent.com/googleworkspace/vscode-extension/main/packages/vscode-extension/assets/scope-diagnostics.png)
+### 🔐 OAuth2 Scope Intelligence
 
-- **MCP (Model Context Protocol) Server**: Registers the Google Workspace Developer Tools MCP server, enabling enhanced development tools.
+Automatically validate and document Google Workspace OAuth2 scopes in your code:
 
-## Usage
+- **Real-time Validation**: Instantly identify invalid or unknown OAuth2 scope URLs
+- **Security Classification**: Visual warnings for restricted and sensitive scopes
+- **Hover Documentation**: See scope descriptions, associated APIs, and documentation links on hover
+- **Multi-API Support**: Coverage for all Google Workspace APIs (Gmail, Drive, Calendar, Chat, Admin, and more)
 
-### OAuth2 Scope Linting
+![OAuth2 Scope Linting](https://raw.githubusercontent.com/googleworkspace/vscode-extension/main/packages/vscode-extension/assets/scope-diagnostics.png)
 
-Warnings and suggestions will automatically appear for OAuth2 scopes in your code.
+**Scope Classifications:**
 
-## Installation
+- 🔴 **Restricted**: Scopes requiring additional verification (e.g., `drive`, `gmail.modify`)
+- 🟡 **Sensitive**: Scopes accessing sensitive user data (e.g., `gmail.readonly`, `calendar`)
+- 🟢 **Non-Sensitive**: Basic access scopes (e.g., `userinfo.email`, `userinfo.profile`)
 
-You can install the Google Workspace Developer Tools extension in a few ways.
+### 🤖 MCP (Model Context Protocol) Server
 
-### From within VS Code (Recommended)
+Integrated support for AI-powered development through the Google Workspace Developer Tools MCP server:
 
-1. Launch Visual Studio Code.
-2. Go to the **Extensions** view (`Ctrl+Shift+X` or `Cmd+Shift+X`).
-3. Search for `Google Workspace Developer Tools`.
-4. Click **Install**.
+- Access Google Workspace API documentation directly in your AI coding assistant
+- Get context-aware suggestions for Google Workspace development
+- Enhanced Copilot and other AI tool capabilities for Google Workspace projects
 
-### From a Marketplace
+## 🚀 Quick Start
 
-Install the extension from your preferred marketplace:
+### Installation
 
-- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=google-workspace.google-workspace-developer-tools)
-- [Open VSX Registry](https://open-vsx.org/extension/google-workspace/google-workspace-developer-tools)
+#### From VS Code (Recommended)
 
-### Using the Command Line
+1. Open Visual Studio Code
+2. Press `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS)
+3. Search for **"Google Workspace Developer Tools"**
+4. Click **Install**
 
-If you have the `code` command-line tool installed, you can install the extension with this command:
+#### From Marketplace
 
-```sh
+- **[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=google-workspace.google-workspace-developer-tools)**
+- **[Open VSX Registry](https://open-vsx.org/extension/google-workspace/google-workspace-developer-tools)**
+
+#### Command Line
+
+```bash
 code --install-extension google-workspace.google-workspace-developer-tools
 ```
+
+### Usage
+
+#### OAuth2 Scope Linting
+
+The extension works automatically once installed:
+
+1. **Write Code**: Include Google OAuth2 scope URLs in your code:
+
+   ```javascript
+   const SCOPES = [
+     "https://www.googleapis.com/auth/gmail.readonly",
+     "https://www.googleapis.com/auth/drive.file",
+   ];
+   ```
+
+2. **Get Instant Feedback**:
+   - Warnings appear for restricted/sensitive scopes
+   - Invalid scopes are highlighted with error diagnostics
+   - Hover over any scope for detailed information
+
+3. **Learn More**: Click on scope URLs in hover tooltips to access official documentation
+
+**Supported File Types**: Works in all text files including JavaScript, TypeScript, Python, JSON, YAML, and more.
+
+## 🔍 How It Works
+
+The extension:
+
+1. Scans your code for Google OAuth2 scope URLs (`https://www.googleapis.com/auth/*`)
+2. Validates them against the official Google API registry
+3. Provides real-time diagnostics based on scope classification
+4. Offers rich hover information with:
+   - Scope description
+   - Security classification
+   - Associated Google Workspace APIs
+   - Links to API documentation
+
+## 📋 Requirements
+
+- Visual Studio Code version 1.50.0 or higher
+- No additional dependencies required
+
+## ⚙️ Extension Settings
+
+This extension works out of the box with no configuration required. Future versions may include customizable settings.
+
+## 🐛 Known Issues
+
+Please report issues on our [GitHub Issues page](https://github.com/googleworkspace/developer-tools/issues).
+
+## 📝 Release Notes
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed release notes and version history.
+
+### Recent Updates
+
+- **0.5.x**: Enhanced scope validation and MCP server integration
+- **0.4.x**: Added support for additional Google Workspace APIs
+- **0.3.x**: Initial public release with OAuth2 scope linting
+
+## 🤝 Contributing
+
+We welcome contributions! This extension is part of the [Google Workspace Developer Tools](https://github.com/googleworkspace/developer-tools) monorepo.
+
+## 📚 Resources
+
+- [Google Workspace APIs Documentation](https://developers.google.com/workspace)
+- [OAuth 2.0 Scopes Reference](https://developers.google.com/identity/protocols/oauth2/scopes)
+- [GitHub Repository](https://github.com/googleworkspace/developer-tools)
+
+## 📄 License
+
+Apache 2.0 License - see [LICENSE](./LICENSE) for details.
+
+## 💬 Support
+
+- 🐛 [Report a Bug](https://github.com/googleworkspace/developer-tools/issues)
+- 💡 [Request a Feature](https://github.com/googleworkspace/developer-tools/issues)
+- 📖 [View Documentation](https://github.com/googleworkspace/developer-tools)
