feat: create docs website (#1696)

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Author: mdesmet

.github/workflows/deploy-docs-to-s3.yaml

@@ -0,0 +1,44 @@
+name: Deploy Static Website to AWS
+
+# Defines when the action will run.
+# This example triggers the workflow on push events to the main branch.
+on:
+  push:
+    branches: [master]
+
+# Limit permissions for the GITHUB_TOKEN to adhere to the principle of least privilege.
+permissions:
+  contents: read
+
+# The jobs that will be executed by the workflow.
+jobs:
+  deploy:
+    # The type of runner that the job will run on.
+    runs-on: ubuntu-latest
+
+    # Steps represent a sequence of tasks that will be executed as part of the job.
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so the job can access it.
+      - uses: actions/checkout@v2
+
+      # Install MkDocs and any necessary plugins
+      - name: Install MkDocs with plugins
+        run: |
+          pip install mkdocs          
+          pip install mkdocs-material
+          pip install mkdocs-git-revision-date-localized-plugin
+
+      # Build your site using MkDocs
+      - name: Build site with MkDocs
+        run: |
+          cd documentation
+          mkdocs build --clean
+
+      # Deploy to AWS
+      - name: Deploy to AWS
+        uses: onramper/[email protected]
+        with:
+          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          domain: docs.myaltimate.com
+          publish_dir: ./documentation/site

CLAUDE.md

@@ -62,15 +62,16 @@ src/
 ### 1. dbt Integration Support
 
 **Multiple Integration Types**:
-- **dbt Core**: Direct Python integration
-- **dbt Cloud**: API-based integration  
-- **dbt Fusion**: Command-line integration
-- **Core Command**: CLI wrapper integration
+- **dbt Core**: Direct Python integration via Python bridge
+- **dbt Cloud**: API-based integration with dbt Cloud services
+- **dbt Fusion**: Command-line integration with dbt-fusion CLI
+- **Core Command**: CLI wrapper integration for dbt core
 
 **Key Integration Files**:
-- `src/dbt_client/dbtCoreIntegration.ts`
-- `src/dbt_client/dbtCloudIntegration.ts`
-- `dbt_core_integration.py` (Python bridge)
+- `src/dbt_client/dbtCoreIntegration.ts` - dbt Core Python integration
+- `src/dbt_client/dbtCloudIntegration.ts` - dbt Cloud API integration
+- `src/dbt_client/dbtFusionCommandIntegration.ts` - dbt Fusion CLI integration
+- `dbt_core_integration.py` - Python bridge for Core integration
 
 ### 2. Language Server Features
 
@@ -268,4 +269,304 @@ Uses VSCode's webview messaging system with typed message contracts. State is sy
 ### 4. Python Bridge Pattern
 For dbt operations requiring Python, use the established bridge pattern with JSON serialization and error handling.
 
-This architecture enables the extension to provide comprehensive dbt development support while maintaining modularity and extensibility for future enhancements.
+This architecture enables the extension to provide comprehensive dbt development support while maintaining modularity and extensibility for future enhancements.
+
+---
+
+# User Guide
+
+## Core Features Overview
+
+The dbt Power User extension accelerates dbt and SQL development by 3x through three key phases:
+
+### 🔧 DEVELOP
+- **SQL Visualizer**: Visual query builder and analyzer
+- **Query Explanation**: AI-powered SQL query explanation
+- **Auto-generation**: Generate dbt models from sources or raw SQL
+- **Auto-completion**: IntelliSense for dbt models, macros, sources, and doc blocks
+- **Click to Run**: Execute models directly from editor
+- **Query Translation**: Translate SQL between different dialects
+- **Compiled SQL Preview**: View compiled dbt code before execution
+
+### 🧪 TEST  
+- **Query Results Preview**: Execute and analyze query results with export capabilities
+- **Test Generation**: AI-powered test generation for dbt models
+- **Column Lineage**: Detailed data lineage with code visibility
+- **Defer to Production**: Run models without rebuilding dependencies
+- **SQL Validation**: Validate SQL without execution
+- **Model Lineage**: Visual representation of model dependencies
+
+### 🤝 COLLABORATE
+- **Documentation Generation**: AI-powered documentation creation
+- **Code Collaboration**: Discussion threads on code and documentation
+- **Project Governance**: Automated checks for code quality and standards
+- **SaaS UI Integration**: Web-based interface for dbt docs and lineage
+- **Query History & Bookmarks**: Track and share query executions
+- **Export Workflows**: Share lineage and documentation externally
+
+## DataMates AI Integration
+
+The extension includes **AI Teammates** through the DataMates Platform:
+- **Coaching**: Personalize AI teammates for specific requirements
+- **Query Assistance**: AI-powered query explanation and optimization
+- **Documentation**: Automated documentation generation
+- **Test Suggestions**: Smart test recommendations
+- **SQL Translation**: Cross-dialect SQL conversion
+
+## Feature Availability
+
+**Free Extension Features**:
+- SQL Visualizer, Model-level lineage, Auto-generation from sources
+- Auto-completion, Click to Run, Compiled SQL preview
+- Query results preview, Defer to production, SQL validation
+
+**With Altimate AI Key** (free signup at [app.myaltimate.com](https://app.myaltimate.com)):
+- Column-level lineage, Query explanation AI, Query translation AI
+- Auto-generation from SQL, Test generation AI, Documentation generation AI
+- Code/documentation collaboration, Lineage export, SaaS UI
+- Project governance, Query history & bookmarks
+
+---
+
+# Installation and Setup
+
+## Installation Methods
+
+### Native Installation
+Install directly from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=innoverio.vscode-dbt-power-user) or via VS Code:
+1. Open VS Code Extensions panel (`Ctrl+Shift+X`)
+2. Search for "dbt Power User"
+3. Click Install
+4. Reload VS Code if prompted
+
+### Dev Container Installation
+Add to your `.devcontainer/devcontainer.json`:
+```json
+{
+  "customizations": {
+    "vscode": {
+      "files.associations": {
+        "*.yaml": "jinja-yaml",
+        "*.yml": "jinja-yaml", 
+        "*.sql": "jinja-sql",
+        "*.md": "jinja-md"
+      },
+      "extensions": [
+        "innoverio.vscode-dbt-power-user"
+      ]
+    }
+  }
+}
+```
+
+### Cursor IDE Support
+The extension is also available for [Cursor IDE](https://www.cursor.com/how-to-install-extension). Install the same way as VS Code.
+
+## Required Configuration
+
+### 1. dbt Integration Setup
+Configure how the extension connects to dbt:
+- **dbt Core**: For local dbt installations with Python bridge (default)
+- **dbt Cloud**: For dbt Cloud API integration
+- **dbt Fusion**: For dbt-fusion CLI integration
+- **dbt Core Command**: For CLI-based dbt core integration
+
+Set via `dbt.dbtIntegration` setting.
+
+#### dbt Fusion Integration
+dbt Fusion is a command-line interface that provides enhanced dbt functionality. When using fusion integration:
+- Requires dbt-fusion CLI to be installed in your environment
+- Extension automatically detects fusion installation via `dbt --version` output
+- Provides full feature support including query execution, compilation, and catalog operations
+- Uses JSON log format for structured command output parsing
+
+### 2. Python Environment
+Ensure Python and dbt are properly installed and accessible. The extension will auto-detect your Python environment through the VS Code Python extension.
+
+### 3. Optional: Altimate AI Key
+For advanced AI features, get a free API key:
+1. Sign up at [app.myaltimate.com/register](https://app.myaltimate.com/register)
+2. Add API key to `dbt.altimateAiKey` setting
+3. Set instance name in `dbt.altimateInstanceName` setting
+
+## Project Setup
+1. Open your dbt project folder in VS Code
+2. Run the setup wizard: Select "dbt" in bottom status bar → "Setup Extension"
+3. The extension will auto-install dbt dependencies if enabled
+4. Verify setup via Command Palette → "dbt Power User: Diagnostics"
+
+---
+
+# Troubleshooting for Developers
+
+## Quick Diagnostics
+
+### 1. Setup Wizard
+Use the built-in setup wizard for automated issue detection:
+- Click "dbt" or "dbt is not installed" in bottom status bar
+- Select "Setup Extension" 
+- Follow guided setup process
+
+### 2. Diagnostics Command
+Run comprehensive system diagnostics:
+- Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
+- Type "diagnostics" → Select "dbt Power User: Diagnostics"
+- Review output for environment issues, Python/dbt installation status, and connection problems
+
+### 3. Problems Panel
+Check VS Code Problems panel for dbt project issues:
+- View → Problems (or `Ctrl+Shift+M`)
+- Look for dbt-related validation errors
+
+## Debug Logging
+
+Enable detailed logging for troubleshooting:
+1. Command Palette → "Set Log Level" → "Debug"
+2. View logs: Output panel → "Log" dropdown → "dbt"
+3. Reproduce the issue to capture debug information
+
+## Developer Tools
+For advanced debugging:
+- Help → Toggle Developer Tools
+- Check console for JavaScript errors and detailed logs
+
+## Common Issues
+
+**Extension not recognizing dbt project**:
+- Verify `dbt_project.yml` exists in workspace root
+- Check Python environment has dbt installed
+- Run diagnostics command for detailed analysis
+
+**Python/dbt not found**:
+- Configure Python interpreter via VS Code Python extension
+- Verify dbt is installed in selected Python environment
+- Set `dbt.dbtPythonPathOverride` if using custom Python path
+
+**Connection issues**:
+- Verify database connection in dbt profiles
+- Check firewall/network settings
+- Review connection details in diagnostics output
+
+## Getting Help
+- Join [#tools-dbt-power-user](https://getdbt.slack.com/archives/C05KPDGRMDW) in dbt Community Slack
+- Contact support at [altimate.ai/support](https://www.altimate.ai/support)
+- Use in-extension feedback widgets for feature-specific issues
+
+---
+
+# Core Development Features
+
+## Auto-completion and Navigation
+
+### Model Auto-completion
+- **Smart IntelliSense**: Auto-complete model names with `ref()` function
+- **Go-to-Definition**: Navigate directly to model files
+- **Hover Information**: View model details on hover
+
+### Macro Support  
+- **Macro Auto-completion**: IntelliSense for custom and built-in macros
+- **Parameter Hints**: Auto-complete macro parameters
+- **Definition Navigation**: Jump to macro definitions
+
+### Source Integration
+- **Source Auto-completion**: IntelliSense for configured sources
+- **Column Awareness**: Auto-complete source column names
+- **Schema Navigation**: Navigate to source definitions
+
+### Documentation Blocks
+- **Doc Block Auto-completion**: IntelliSense for documentation references
+- **Definition Linking**: Navigate to doc block definitions
+
+## Query Development
+
+### SQL Compilation and Preview
+- **Compiled Code View**: See final SQL before execution
+- **Template Resolution**: Preview Jinja templating results
+- **Syntax Highlighting**: Enhanced SQL syntax highlighting for dbt files
+
+### Query Execution
+- **Preview Results**: Execute queries with `Cmd+Enter` / `Ctrl+Enter`
+- **Result Analysis**: Export results as CSV, copy as JSON
+- **Query History**: Track executed queries
+- **Configurable Limits**: Set row limits for query previews (default: 500 rows)
+
+### SQL Formatting
+- **Auto-formatting**: Integration with sqlfmt
+- **Custom Parameters**: Configure formatting rules
+- **Batch Processing**: Format multiple files
+
+## AI-Powered Development
+
+### Query Explanation
+- **Natural Language**: Get plain English explanations of complex SQL
+- **Step-by-step Analysis**: Breakdown of query logic
+- **Performance Insights**: Query optimization suggestions
+
+### Code Generation
+- **Model from Source**: Generate base models from source tables
+- **Model from SQL**: Convert raw SQL to dbt models
+- **Test Generation**: AI-powered test suggestions
+- **Documentation Generation**: Auto-generate model documentation
+
+### Query Translation
+- **Cross-dialect Support**: Translate SQL between database dialects
+- **Syntax Adaptation**: Handle dialect-specific functions and syntax
+
+## Documentation
+
+This is a MkDocs-based documentation site for the dbt Power User VSCode Extension by Altimate AI. The site uses the Material theme and is organized around user workflows: Develop, Test, and Collaborate.
+
+### Development Commands
+
+- **Install dependencies**: `pip install --requirement documentation/requirements.txt`
+- **Start development server**: `cd documentation; mkdocs serve` (serves at http://127.0.0.1:8000)
+- **Build site**: `cd documentation; mkdocs build`
+- **Deploy to GitHub Pages**: `cd documentation; mkdocs gh-deploy`
+
+### Architecture
+
+#### Content Organization
+- `documentation/docs/` contains all documentation content in Markdown format
+- Content is organized by feature areas: `setup/`, `develop/`, `test/`, `document/`, `govern/`, `discover/`, `teammates/`, `datamates/`, `arch/`
+- Images and assets are stored within feature-specific directories
+- `documentation/mkdocs.yml` contains all site configuration
+
+#### Key Configuration Files
+- `documentation/mkdocs.yml`: Main site configuration including navigation, theme settings, and plugins
+- `documentation/requirements.txt`: Python dependencies for MkDocs and plugins
+- `documentation/docs/overrides/`: Custom theme overrides (currently empty)
+- `documentation/docs/javascripts/`: Custom JavaScript for enhanced functionality
+
+#### Theme Configuration
+The site uses Material theme with:
+- Custom Altimate AI branding and colors
+- Google Analytics integration (G-LXRSS3VK5N)
+- Git revision date tracking via plugin
+- Built-in feedback system
+- Dark/light mode support
+
+#### Navigation Structure
+Navigation follows a three-phase user journey:
+1. **Setup**: Installation and configuration
+2. **Develop**: Core development features
+3. **Test**: Testing and validation tools
+4. **Additional**: Documentation, collaboration, discovery, and AI features
+
+### Working with Content
+
+#### Adding New Pages
+1. Create `.md` files in the appropriate `docs/` subdirectory
+2. Update the `nav` section in `mkdocs.yml` to include the new page
+3. Follow existing naming conventions for consistency
+
+#### Images and Assets
+- Store images in the same directory as the referencing markdown file
+- Use relative paths for image references
+- Common assets go in `docs/assets/`
+
+#### Internal Links
+Use relative markdown links to reference other pages. The site has extensive cross-referencing between related features.
+
+### Testing Changes
+
+Always test locally with `mkdocs serve` before deploying. The development server provides live reload for content changes.