refactor(dashboard): use logger.exception for cleaner error logging

Replace logger.error with exc_info=True with logger.exception() for more concise and idiomatic exception logging in thumbnail retrieval.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.asf.yaml

@@ -83,7 +83,6 @@ github:
           - cypress-matrix (5, chrome)
           - dependency-review
           - frontend-build
-          - playwright-tests (chromium)
           - pre-commit (current)
           - pre-commit (previous)
           - test-mysql

.devcontainer/README.md

@@ -3,3 +3,14 @@
 For complete documentation on using GitHub Codespaces with Apache Superset, please see:
 
 **[Setting up a Development Environment - GitHub Codespaces](https://superset.apache.org/docs/contributing/development#github-codespaces-cloud-development)**
+
+## Pre-installed Development Environment
+
+When you create a new Codespace from this repository, it automatically:
+
+1. **Creates a Python virtual environment** using `uv venv`
+2. **Installs all development dependencies** via `uv pip install -r requirements/development.txt`
+3. **Sets up pre-commit hooks** with `pre-commit install`
+4. **Activates the virtual environment** automatically in all terminals
+
+The virtual environment is located at `/workspaces/{repository-name}/.venv` and is automatically activated through environment variables set in the devcontainer configuration.

.devcontainer/default/devcontainer.json

@@ -1,19 +0,0 @@
-{
-  // Extend the base configuration
-  "extends": "../devcontainer-base.json",
-
-  "name": "Apache Superset Development (Default)",
-
-  // Forward ports for development
-  "forwardPorts": [9001],
-  "portsAttributes": {
-    "9001": {
-      "label": "Superset (via Webpack Dev Server)",
-      "onAutoForward": "notify",
-      "visibility": "public"
-    }
-  },
-
-  // Auto-start Superset on Codespace resume
-  "postStartCommand": ".devcontainer/start-superset.sh"
-}

.devcontainer/devcontainer-base.json

@@ -1,39 +0,0 @@
-{
-  "name": "Apache Superset Development",
-  // Keep this in sync with the base image in Dockerfile (ARG PY_VER)
-  // Using the same base as Dockerfile, but non-slim for dev tools
-  "image": "python:3.11.13-bookworm",
-
-  "features": {
-    "ghcr.io/devcontainers/features/docker-in-docker:2": {
-      "moby": true,
-      "dockerDashComposeVersion": "v2"
-    },
-    "ghcr.io/devcontainers/features/node:1": {
-      "version": "20"
-    },
-    "ghcr.io/devcontainers/features/git:1": {},
-    "ghcr.io/devcontainers/features/common-utils:2": {
-      "configureZshAsDefaultShell": true
-    },
-    "ghcr.io/devcontainers/features/sshd:1": {
-      "version": "latest"
-    }
-  },
-
-  // Run commands after container is created
-  "postCreateCommand": "chmod +x .devcontainer/setup-dev.sh && .devcontainer/setup-dev.sh",
-
-  // VS Code customizations
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "ms-python.python",
-        "ms-python.vscode-pylance",
-        "charliermarsh.ruff",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode"
-      ]
-    }
-  }
-}

.devcontainer/setup-dev.sh

@@ -3,30 +3,76 @@
 
 echo "🔧 Setting up Superset development environment..."
 
-# The universal image has most tools, just need Superset-specific libs
-echo "📦 Installing Superset-specific dependencies..."
-sudo apt-get update
-sudo apt-get install -y \
-    libsasl2-dev \
-    libldap2-dev \
-    libpq-dev \
-    tmux \
-    gh
+# System dependencies and uv are now pre-installed in the Docker image
+# This speeds up Codespace creation significantly!
 
-# Install uv for fast Python package management
-echo "📦 Installing uv..."
-curl -LsSf https://astral.sh/uv/install.sh | sh
+# Create virtual environment using uv
+echo "🐍 Creating Python virtual environment..."
+if ! uv venv; then
+    echo "❌ Failed to create virtual environment"
+    exit 1
+fi
 
-# Add cargo/bin to PATH for uv
-echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
-echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
+# Install Python dependencies
+echo "📦 Installing Python dependencies..."
+if ! uv pip install -r requirements/development.txt; then
+    echo "❌ Failed to install Python dependencies"
+    echo "💡 You may need to run this manually after the Codespace starts"
+    exit 1
+fi
+
+# Install pre-commit hooks
+echo "🪝 Installing pre-commit hooks..."
+if source .venv/bin/activate && pre-commit install; then
+    echo "✅ Pre-commit hooks installed"
+else
+    echo "⚠️  Pre-commit hooks installation failed (non-critical)"
+fi
 
 # Install Claude Code CLI via npm
 echo "🤖 Installing Claude Code..."
-npm install -g @anthropic-ai/claude-code
+if npm install -g @anthropic-ai/claude-code; then
+    echo "✅ Claude Code installed"
+else
+    echo "⚠️  Claude Code installation failed (non-critical)"
+fi
 
 # Make the start script executable
 chmod +x .devcontainer/start-superset.sh
 
+# Add bashrc additions for automatic venv activation
+echo "🔧 Setting up automatic environment activation..."
+if [ -f ~/.bashrc ]; then
+    # Check if we've already added our additions
+    if ! grep -q "Superset Codespaces environment setup" ~/.bashrc; then
+        echo "" >> ~/.bashrc
+        cat .devcontainer/bashrc-additions >> ~/.bashrc
+        echo "✅ Added automatic venv activation to ~/.bashrc"
+    else
+        echo "✅ Bashrc additions already present"
+    fi
+else
+    # Create bashrc if it doesn't exist
+    cat .devcontainer/bashrc-additions > ~/.bashrc
+    echo "✅ Created ~/.bashrc with automatic venv activation"
+fi
+
+# Also add to zshrc since that's the default shell
+if [ -f ~/.zshrc ] || [ -n "$ZSH_VERSION" ]; then
+    if ! grep -q "Superset Codespaces environment setup" ~/.zshrc; then
+        echo "" >> ~/.zshrc
+        cat .devcontainer/bashrc-additions >> ~/.zshrc
+        echo "✅ Added automatic venv activation to ~/.zshrc"
+    fi
+fi
+
 echo "✅ Development environment setup complete!"
-echo "🚀 Run '.devcontainer/start-superset.sh' to start Superset"
+echo ""
+echo "📝 The virtual environment will be automatically activated in new terminals"
+echo ""
+echo "🔄 To activate in this terminal, run:"
+echo "   source ~/.bashrc"
+echo ""
+echo "🚀 To start Superset:"
+echo "   start-superset"
+echo ""

.devcontainer/start-superset.sh

@@ -1,14 +1,14 @@
 #!/bin/bash
 # Startup script for Superset in Codespaces
 
+# Log to a file for debugging
+LOG_FILE="/tmp/superset-startup.log"
+echo "[$(date)] Starting Superset startup script" >> "$LOG_FILE"
+echo "[$(date)] User: $(whoami), PWD: $(pwd)" >> "$LOG_FILE"
+
 echo "🚀 Starting Superset in Codespaces..."
 echo "🌐 Frontend will be available at port 9001"
 
-# Check if MCP is enabled
-if [ "$ENABLE_MCP" = "true" ]; then
-    echo "🤖 MCP Service will be available at port 5008"
-fi
-
 # Find the workspace directory (Codespaces clones as 'superset', not 'superset-2')
 WORKSPACE_DIR=$(find /workspaces -maxdepth 1 -name "superset*" -type d | head -1)
 if [ -n "$WORKSPACE_DIR" ]; then
@@ -18,32 +18,71 @@ else
     echo "📁 Using current directory: $(pwd)"
 fi
 
-# Check if docker is running
-if ! docker info > /dev/null 2>&1; then
-    echo "⏳ Waiting for Docker to start..."
-    sleep 5
+# Wait for Docker to be available
+echo "⏳ Waiting for Docker to start..."
+echo "[$(date)] Waiting for Docker..." >> "$LOG_FILE"
+max_attempts=30
+attempt=0
+while ! docker info > /dev/null 2>&1; do
+    if [ $attempt -eq $max_attempts ]; then
+        echo "❌ Docker failed to start after $max_attempts attempts"
+        echo "[$(date)] Docker failed to start after $max_attempts attempts" >> "$LOG_FILE"
+        echo "🔄 Please restart the Codespace or run this script manually later"
+        exit 1
+    fi
+    echo "   Attempt $((attempt + 1))/$max_attempts..."
+    echo "[$(date)] Docker check attempt $((attempt + 1))/$max_attempts" >> "$LOG_FILE"
+    sleep 2
+    attempt=$((attempt + 1))
+done
+echo "✅ Docker is ready!"
+echo "[$(date)] Docker is ready" >> "$LOG_FILE"
+
+# Check if Superset containers are already running
+if docker ps | grep -q "superset"; then
+    echo "✅ Superset containers are already running!"
+    echo ""
+    echo "🌐 To access Superset:"
+    echo "   1. Click the 'Ports' tab at the bottom of VS Code"
+    echo "   2. Find port 9001 and click the globe icon to open"
+    echo "   3. Wait 10-20 minutes for initial startup"
+    echo ""
+    echo "📝 Login credentials: admin/admin"
+    exit 0
 fi
 
 # Clean up any existing containers
 echo "🧹 Cleaning up existing containers..."
-docker-compose -f docker-compose-light.yml --profile mcp down
+docker-compose -f docker-compose-light.yml down
 
 # Start services
-echo "🏗️  Building and starting services..."
+echo "🏗️  Starting Superset in background (daemon mode)..."
 echo ""
-echo "📝 Once started, login with:"
-echo "   Username: admin"
-echo "   Password: admin"
-echo ""
-echo "📋 Running in foreground with live logs (Ctrl+C to stop)..."
 
-# Run docker-compose and capture exit code
-if [ "$ENABLE_MCP" = "true" ]; then
-    echo "🤖 Starting with MCP Service enabled..."
-    docker-compose -f docker-compose-light.yml --profile mcp up
-else
-    docker-compose -f docker-compose-light.yml up
-fi
+# Start in detached mode
+docker-compose -f docker-compose-light.yml up -d
+
+echo ""
+echo "✅ Docker Compose started successfully!"
+echo ""
+echo "📋 Important information:"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "⏱️  Initial startup takes 10-20 minutes"
+echo "🌐 Check the 'Ports' tab for your Superset URL (port 9001)"
+echo "👤 Login: admin / admin"
+echo ""
+echo "📊 Useful commands:"
+echo "   docker-compose -f docker-compose-light.yml logs -f    # Follow logs"
+echo "   docker-compose -f docker-compose-light.yml ps         # Check status"
+echo "   docker-compose -f docker-compose-light.yml down       # Stop services"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "💤 Keeping terminal open for 60 seconds to test persistence..."
+sleep 60
+echo "✅ Test complete - check if this terminal is still visible!"
+
+# Show final status
+docker-compose -f docker-compose-light.yml ps
 EXIT_CODE=$?
 
 # If it failed, provide helpful instructions

.devcontainer/with-mcp/devcontainer.json

@@ -1,29 +0,0 @@
-{
-  // Extend the base configuration
-  "extends": "../devcontainer-base.json",
-
-  "name": "Apache Superset Development with MCP",
-
-  // Forward ports for development
-  "forwardPorts": [9001, 5008],
-  "portsAttributes": {
-    "9001": {
-      "label": "Superset (via Webpack Dev Server)",
-      "onAutoForward": "notify",
-      "visibility": "public"
-    },
-    "5008": {
-      "label": "MCP Service (Model Context Protocol)",
-      "onAutoForward": "notify",
-      "visibility": "private"
-    }
-  },
-
-  // Auto-start Superset with MCP on Codespace resume
-  "postStartCommand": "ENABLE_MCP=true .devcontainer/start-superset.sh",
-
-  // Environment variables
-  "containerEnv": {
-    "ENABLE_MCP": "true"
-  }
-}

.github/CODEOWNERS

@@ -33,7 +33,6 @@
 
 # Notify PMC members of changes to extension-related files
 
-/docs/developer_portal/extensions/ @michael-s-molina @villebro @rusackas
 /superset-core/ @michael-s-molina @villebro @geido @eschutho @rusackas @kgabryje
 /superset-extensions-cli/ @michael-s-molina @villebro @geido @eschutho @rusackas @kgabryje
 /superset/core/ @michael-s-molina @villebro @geido @eschutho @rusackas @kgabryje

.github/workflows/bashlib.sh

@@ -195,7 +195,6 @@ playwright-install() {
 
 playwright-run() {
   local APP_ROOT=$1
-  local TEST_PATH=$2
 
   # Start Flask from the project root (same as Cypress)
   cd "$GITHUB_WORKSPACE"
@@ -239,26 +238,8 @@ playwright-run() {
 
   say "::group::Run Playwright tests"
   echo "Running Playwright with baseURL: ${PLAYWRIGHT_BASE_URL}"
-  if [ -n "$TEST_PATH" ]; then
-    # Check if there are any test files in the specified path
-    if ! find "playwright/tests/${TEST_PATH}" -name "*.spec.ts" -type f 2>/dev/null | grep -q .; then
-      echo "No test files found in ${TEST_PATH} - skipping test run"
-      say "::endgroup::"
-      kill $flaskProcessId
-      return 0
-    fi
-    echo "Running tests: ${TEST_PATH}"
-    # Set INCLUDE_EXPERIMENTAL=true to allow experimental tests to run
-    export INCLUDE_EXPERIMENTAL=true
-    npx playwright test "${TEST_PATH}" --output=playwright-results
-    local status=$?
-    # Unset to prevent leaking into subsequent commands
-    unset INCLUDE_EXPERIMENTAL
-  else
-    echo "Running all required tests (experimental/ excluded via playwright.config.ts)"
-    npx playwright test --output=playwright-results
-    local status=$?
-  fi
+  npx playwright test auth/login --reporter=github --output=playwright-results
+  local status=$?
   say "::endgroup::"
 
   # After job is done, print out Flask log for debugging

.github/workflows/bump-python-package.yml

@@ -32,7 +32,7 @@ jobs:
     steps:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: true
           ref: master

.github/workflows/cancel_duplicates.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
         if: steps.check_queued.outputs.count >= 20
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
 
       - name: Cancel duplicate workflow runs
         if: steps.check_queued.outputs.count >= 20

.github/workflows/check-python-deps.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/check_db_migration_confict.yml

@@ -25,7 +25,7 @@ jobs:
       pull-requests: write
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
       - name: Check and notify
         uses: actions/github-script@v8
         with:

.github/workflows/claude.yml

@@ -71,7 +71,7 @@ jobs:
       id-token: write
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v6
+      uses: actions/checkout@v5
       with:
         fetch-depth: 1
 

.github/workflows/codeql-analysis.yml

@@ -31,7 +31,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
 
       - name: Check for file changes
         id: check

.github/workflows/dependency-review.yml

@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout Repository"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
       - name: "Dependency Review"
         uses: actions/dependency-review-action@v4
         continue-on-error: true
@@ -53,7 +53,7 @@ jobs:
     runs-on: ubuntu-22.04
     steps:
       - name: "Checkout Repository"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
 
       - name: Setup Python
         uses: ./.github/actions/setup-backend/

.github/workflows/docker.yml

@@ -42,7 +42,7 @@ jobs:
     steps:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
 
@@ -117,7 +117,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
       - name: Check for file changes

.github/workflows/embedded-sdk-release.yml

@@ -28,7 +28,7 @@ jobs:
       run:
         working-directory: superset-embedded-sdk
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
         with:
           node-version-file: './superset-embedded-sdk/.nvmrc'

.github/workflows/embedded-sdk-test.yml

@@ -18,7 +18,7 @@ jobs:
       run:
         working-directory: superset-embedded-sdk
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v5
       - uses: actions/setup-node@v5
         with:
           node-version-file: './superset-embedded-sdk/.nvmrc'

.github/workflows/ephemeral-env.yml

@@ -160,7 +160,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ needs.ephemeral-env-label.outputs.sha }} : ${{steps.get-sha.outputs.sha}} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           ref: ${{ needs.ephemeral-env-label.outputs.sha }}
           persist-credentials: false
@@ -220,7 +220,7 @@ jobs:
       pull-requests: write
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v5
         with:
           persist-credentials: false
 

.github/workflows/generate-FOSSA-report.yml

@@ -27,7 +27,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/github-action-validator.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
         uses: actions/setup-node@v5

.github/workflows/issue_creation.yml

@@ -17,7 +17,7 @@ jobs:
     steps:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
 

.github/workflows/latest-release-tag.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
     - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-      uses: actions/checkout@v6
+      uses: actions/checkout@v5
       with:
         persist-credentials: false
         submodules: recursive

.github/workflows/license-check.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/pr-lint.yml

@@ -16,7 +16,7 @@ jobs:
       pull-requests: write
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/pre-commit.yml

@@ -21,7 +21,7 @@ jobs:
         python-version: ["current", "previous", "next"]
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
@@ -71,9 +71,7 @@ jobs:
           GIT_DIFF_EXIT_CODE=$?
           if [ "${PRE_COMMIT_EXIT_CODE}" -ne 0 ] || [ "${GIT_DIFF_EXIT_CODE}" -ne 0 ]; then
             if [ "${PRE_COMMIT_EXIT_CODE}" -ne 0 ]; then
-              echo "❌ Pre-commit check failed (exit code: ${PRE_COMMIT_EXIT_CODE})."
-              echo "🔍 Modified files:"
-              git diff --name-only
+              echo "❌ Pre-commit check failed (exit code: ${EXIT_CODE})."
             else
               echo "❌ Git working directory is dirty."
               echo "📌 This likely means that pre-commit made changes that were not committed."

.github/workflows/prefer-typescript.yml

@@ -27,7 +27,7 @@ jobs:
       pull-requests: write
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/release.yml

@@ -26,7 +26,7 @@ jobs:
     name: Bump version and publish package(s)
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v5
         with:
           # pulls all commits (needed for lerna / semantic release to correctly version)
           fetch-depth: 0

.github/workflows/showtime-trigger.yml

@@ -147,7 +147,7 @@ jobs:
 
       - name: Checkout PR code (only if build needed)
         if: steps.auth.outputs.authorized == 'true' && steps.check.outputs.build_needed == 'true'
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           ref: ${{ steps.check.outputs.target_sha }}
           persist-credentials: false

.github/workflows/superset-app-cli.yml

@@ -37,7 +37,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-applitool-cypress.yml

@@ -51,7 +51,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-applitools-storybook.yml

@@ -30,7 +30,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-docs-deploy.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-docs-verify.yml

@@ -18,10 +18,10 @@ jobs:
     name: Link Checking
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v5
       # Do not bump this linkinator-action version without opening
       # an ASF Infra ticket to allow the new version first!
-      - uses: JustinBeckwith/linkinator-action@af984b9f30f63e796ae2ea5be5e07cb587f1bbd9  # v2.3
+      - uses: JustinBeckwith/linkinator-action@3d5ba091319fa7b0ac14703761eebb7d100e6f6d  # v1.11.0
         continue-on-error: true # This will make the job advisory (non-blocking, no red X)
         with:
           paths: "**/*.md, **/*.mdx"
@@ -58,7 +58,7 @@ jobs:
         working-directory: docs
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-e2e.yml

@@ -69,21 +69,21 @@ jobs:
       # Conditional checkout based on context
       - name: Checkout for push or pull_request event
         if: github.event_name == 'push' || github.event_name == 'pull_request'
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
       - name: Checkout using ref (workflow_dispatch)
         if: github.event_name == 'workflow_dispatch' && github.event.inputs.ref != ''
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           ref: ${{ github.event.inputs.ref }}
           submodules: recursive
       - name: Checkout using PR ID (workflow_dispatch)
         if: github.event_name == 'workflow_dispatch' && github.event.inputs.pr_id != ''
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           ref: refs/pull/${{ github.event.inputs.pr_id }}/merge
@@ -151,118 +151,3 @@ jobs:
         with:
           path: ${{ github.workspace }}/superset-frontend/cypress-base/cypress/screenshots
           name: cypress-artifact-${{ github.run_id }}-${{ github.job }}-${{ matrix.browser }}-${{ matrix.parallel_id }}--${{ steps.set-safe-app-root.outputs.safe_app_root }}
-
-  playwright-tests:
-    runs-on: ubuntu-22.04
-    permissions:
-      contents: read
-      pull-requests: read
-    strategy:
-      fail-fast: false
-      matrix:
-        browser: ["chromium"]
-        app_root: ["", "/app/prefix"]
-    env:
-      SUPERSET_ENV: development
-      SUPERSET_CONFIG: tests.integration_tests.superset_test_config
-      SUPERSET__SQLALCHEMY_DATABASE_URI: postgresql+psycopg2://superset:superset@127.0.0.1:15432/superset
-      PYTHONPATH: ${{ github.workspace }}
-      REDIS_PORT: 16379
-      GITHUB_TOKEN: ${{ github.token }}
-    services:
-      postgres:
-        image: postgres:16-alpine
-        env:
-          POSTGRES_USER: superset
-          POSTGRES_PASSWORD: superset
-        ports:
-          - 15432:5432
-      redis:
-        image: redis:7-alpine
-        ports:
-          - 16379:6379
-    steps:
-      # -------------------------------------------------------
-      # Conditional checkout based on context (same as Cypress workflow)
-      - name: Checkout for push or pull_request event
-        if: github.event_name == 'push' || github.event_name == 'pull_request'
-        uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-          submodules: recursive
-          ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-      - name: Checkout using ref (workflow_dispatch)
-        if: github.event_name == 'workflow_dispatch' && github.event.inputs.ref != ''
-        uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-          ref: ${{ github.event.inputs.ref }}
-          submodules: recursive
-      - name: Checkout using PR ID (workflow_dispatch)
-        if: github.event_name == 'workflow_dispatch' && github.event.inputs.pr_id != ''
-        uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-          ref: refs/pull/${{ github.event.inputs.pr_id }}/merge
-          submodules: recursive
-      # -------------------------------------------------------
-      - name: Check for file changes
-        id: check
-        uses: ./.github/actions/change-detector/
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Setup Python
-        uses: ./.github/actions/setup-backend/
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-      - name: Setup postgres
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        with:
-          run: setup-postgres
-      - name: Import test data
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        with:
-          run: testdata
-      - name: Setup Node.js
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: actions/setup-node@v5
-        with:
-          node-version-file: './superset-frontend/.nvmrc'
-      - name: Install npm dependencies
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        with:
-          run: npm-install
-      - name: Build javascript packages
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        with:
-          run: build-instrumented-assets
-      - name: Install Playwright
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        with:
-          run: playwright-install
-      - name: Run Playwright (Required Tests)
-        if: steps.check.outputs.python || steps.check.outputs.frontend
-        uses: ./.github/actions/cached-dependencies
-        env:
-          NODE_OPTIONS: "--max-old-space-size=4096"
-        with:
-          run: playwright-run "${{ matrix.app_root }}"
-      - name: Set safe app root
-        if: failure()
-        id: set-safe-app-root
-        run: |
-          APP_ROOT="${{ matrix.app_root }}"
-          SAFE_APP_ROOT=${APP_ROOT//\//_}
-          echo "safe_app_root=$SAFE_APP_ROOT" >> $GITHUB_OUTPUT
-      - name: Upload Playwright Artifacts
-        uses: actions/upload-artifact@v4
-        if: failure()
-        with:
-          path: |
-            ${{ github.workspace }}/superset-frontend/playwright-results/
-            ${{ github.workspace }}/superset-frontend/test-results/
-          name: playwright-artifact-${{ github.run_id }}-${{ github.job }}-${{ matrix.browser }}--${{ steps.set-safe-app-root.outputs.safe_app_root }}

.github/workflows/superset-extensions-cli.yml

@@ -24,7 +24,7 @@ jobs:
         working-directory: superset-extensions-cli
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-frontend.yml

@@ -23,7 +23,7 @@ jobs:
       should-run: ${{ steps.check.outputs.frontend }}
     steps:
       - name: Checkout Code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           fetch-depth: 0
@@ -135,15 +135,15 @@ jobs:
         run: |
           docker load < docker-image.tar.gz
 
-      - name: lint
+      - name: eslint
         run: |
           docker run --rm $TAG bash -c \
-          "npm i && npm run lint"
+          "npm i && npm run eslint -- . --quiet"
 
       - name: tsc
         run: |
           docker run --rm $TAG bash -c \
-          "npm i && npm run plugins:build && npm run type"
+          "npm run plugins:build && npm run type"
 
   validate-frontend:
     needs: frontend-build

.github/workflows/superset-helm-lint.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-helm-release.yml

@@ -29,7 +29,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           ref: ${{ inputs.ref || github.ref_name }}
           persist-credentials: true

.github/workflows/superset-playwright.yml

@@ -1,4 +1,4 @@
-name: Playwright Experimental Tests
+name: Playwright E2E Tests
 
 on:
   push:
@@ -23,10 +23,9 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # NOTE: Required Playwright tests are in superset-e2e.yml (E2E / playwright-tests)
-  # This workflow contains only experimental tests that run in shadow mode
-  playwright-tests-experimental:
+  playwright-tests:
     runs-on: ubuntu-22.04
+    # Allow workflow to succeed even if tests fail during shadow mode
     continue-on-error: true
     permissions:
       contents: read
@@ -60,21 +59,21 @@ jobs:
       # Conditional checkout based on context (same as Cypress workflow)
       - name: Checkout for push or pull_request event
         if: github.event_name == 'push' || github.event_name == 'pull_request'
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
           ref: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
       - name: Checkout using ref (workflow_dispatch)
         if: github.event_name == 'workflow_dispatch' && github.event.inputs.ref != ''
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           ref: ${{ github.event.inputs.ref }}
           submodules: recursive
       - name: Checkout using PR ID (workflow_dispatch)
         if: github.event_name == 'workflow_dispatch' && github.event.inputs.pr_id != ''
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           ref: refs/pull/${{ github.event.inputs.pr_id }}/merge
@@ -118,13 +117,13 @@ jobs:
         uses: ./.github/actions/cached-dependencies
         with:
           run: playwright-install
-      - name: Run Playwright (Experimental Tests)
+      - name: Run Playwright
         if: steps.check.outputs.python || steps.check.outputs.frontend
         uses: ./.github/actions/cached-dependencies
         env:
           NODE_OPTIONS: "--max-old-space-size=4096"
         with:
-          run: playwright-run "${{ matrix.app_root }}" experimental/
+          run: playwright-run ${{ matrix.app_root }}
       - name: Set safe app root
         if: failure()
         id: set-safe-app-root
@@ -139,4 +138,4 @@ jobs:
           path: |
             ${{ github.workspace }}/superset-frontend/playwright-results/
             ${{ github.workspace }}/superset-frontend/test-results/
-          name: playwright-experimental-artifact-${{ github.run_id }}-${{ github.job }}-${{ matrix.browser }}--${{ steps.set-safe-app-root.outputs.safe_app_root }}
+          name: playwright-artifact-${{ github.run_id }}-${{ github.job }}-${{ matrix.browser }}--${{ steps.set-safe-app-root.outputs.safe_app_root }}

.github/workflows/superset-python-integrationtest.yml

@@ -41,7 +41,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
@@ -99,7 +99,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
@@ -152,7 +152,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-python-presto-hive.yml

@@ -48,7 +48,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
@@ -108,7 +108,7 @@ jobs:
           - 16379:6379
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-python-unittest.yml

@@ -24,7 +24,7 @@ jobs:
       PYTHONPATH: ${{ github.workspace }}
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-translations.yml

@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive
@@ -49,7 +49,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
           submodules: recursive

.github/workflows/superset-websocket.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
       - name: Install dependencies

.github/workflows/supersetbot.yml

@@ -38,7 +38,7 @@ jobs:
             });
 
       - name: "Checkout ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           persist-credentials: false
 

.github/workflows/tag-release.yml

@@ -47,7 +47,7 @@ jobs:
     steps:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -107,7 +107,7 @@ jobs:
     steps:
 
       - name: "Checkout ${{ github.ref }} ( ${{ github.sha }} )"
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 

.github/workflows/tech-debt.yml

@@ -27,7 +27,7 @@ jobs:
     name: Generate Reports
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v6
+        uses: actions/checkout@v5
 
       - name: Set up Node.js
         uses: actions/setup-node@v5

.gitignore

@@ -33,7 +33,6 @@ cover
 .env
 .envrc
 .idea
-.roo
 .mypy_cache
 .python-version
 .tox
@@ -122,8 +121,6 @@ docker/requirements-local.txt
 
 cache/
 docker/*local*
-docker/superset-websocket/config.json
-docker-compose.override.yml
 
 .temp_cache
 
@@ -137,5 +134,3 @@ PROJECT.md
 .aider*
 .claude_rc*
 .env.local
-oxc-custom-build/
-*.code-workspace

.pre-commit-config.yaml

@@ -60,23 +60,9 @@ repos:
         args: ["--markdown-linebreak-ext=md"]
   - repo: local
     hooks:
-      - id: prettier-frontend
-        name: prettier (frontend)
-        entry: bash -c 'cd superset-frontend && for file in "$@"; do npx prettier --write "${file#superset-frontend/}"; done'
-        language: system
-        pass_filenames: true
-        files: ^superset-frontend/.*\.(js|jsx|ts|tsx|css|scss|sass|json)$
-  - repo: local
-    hooks:
-      - id: oxlint-frontend
-        name: oxlint (frontend)
-        entry: ./scripts/oxlint.sh
-        language: system
-        pass_filenames: true
-        files: ^superset-frontend/.*\.(js|jsx|ts|tsx)$
-      - id: custom-rules-frontend
-        name: custom rules (frontend)
-        entry: ./scripts/check-custom-rules.sh
+      - id: eslint-frontend
+        name: eslint (frontend)
+        entry: ./scripts/eslint.sh
         language: system
         pass_filenames: true
         files: ^superset-frontend/.*\.(js|jsx|ts|tsx)$
@@ -106,19 +92,12 @@ repos:
         files: helm
         verbose: false
         args: ["--log-level", "error"]
-  # Using local hooks ensures ruff version matches requirements/development.txt
-  - repo: local
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.7
     hooks:
       - id: ruff-format
-        name: ruff-format
-        entry: ruff format
-        language: system
-        types: [python]
       - id: ruff
-        name: ruff
-        entry: ruff check --fix --show-fixes
-        language: system
-        types: [python]
+        args: [--fix]
   - repo: local
     hooks:
       - id: pylint
@@ -131,12 +110,9 @@ repos:
           - -c
           - |
             TARGET_BRANCH=${GITHUB_BASE_REF:-master}
-            # Only fetch if we're not in CI (CI already has all refs)
-            if [ -z "$CI" ]; then
-              git fetch --no-recurse-submodules origin "$TARGET_BRANCH" 2>/dev/null || true
-            fi
-            BASE=$(git merge-base origin/"$TARGET_BRANCH" HEAD 2>/dev/null) || BASE="HEAD"
-            files=$(git diff --name-only --diff-filter=ACM "$BASE"..HEAD 2>/dev/null | grep '^superset/.*\.py$' || true)
+            git fetch origin "$TARGET_BRANCH"
+            BASE=$(git merge-base origin/"$TARGET_BRANCH" HEAD)
+            files=$(git diff --name-only --diff-filter=ACM "$BASE"..HEAD | grep '^superset/.*\.py$' || true)
             if [ -n "$files" ]; then
               pylint --rcfile=.pylintrc --load-plugins=superset.extensions.pylint --reports=no $files
             else

.pylintrc

@@ -53,7 +53,7 @@ extension-pkg-whitelist=pyarrow
 
 [MESSAGES CONTROL]
 disable=all
-enable=json-import,disallowed-sql-import,consider-using-transaction
+enable=disallowed-json-import,disallowed-sql-import,consider-using-transaction
 
 
 [REPORTS]

.rat-excludes

@@ -11,7 +11,6 @@
 .nvmrc
 .prettierrc
 .rat-excludes
-.swcrc
 .*log
 .*pyc
 .*lock

CONTRIBUTING.md

@@ -25,14 +25,14 @@ little bit helps, and credit will always be given.
 
 All developer and contribution documentation has moved to the Apache Superset Developer Portal:
 
-**[📚 View the Developer Portal →](https://superset.apache.org/developer_portal/)**
+**[📚 View the Developer Portal →](https://superset.apache.org/docs/developer-portal/)**
 
 The Developer Portal includes comprehensive guides for:
-- [Contributing Overview](https://superset.apache.org/developer_portal/contributing/overview)
-- [Development Setup](https://superset.apache.org/developer_portal/contributing/development-setup)
-- [Submitting Pull Requests](https://superset.apache.org/developer_portal/contributing/submitting-pr)
-- [Contribution Guidelines](https://superset.apache.org/developer_portal/contributing/guidelines)
-- [Code Review Process](https://superset.apache.org/developer_portal/contributing/code-review)
-- [Development How-tos](https://superset.apache.org/developer_portal/contributing/howtos)
+- [Contributing Overview](https://superset.apache.org/docs/developer-portal/contributing/overview)
+- [Development Setup](https://superset.apache.org/docs/developer-portal/contributing/development-setup)
+- [Submitting Pull Requests](https://superset.apache.org/docs/developer-portal/contributing/submitting-pr)
+- [Contribution Guidelines](https://superset.apache.org/docs/developer-portal/contributing/guidelines)
+- [Code Review Process](https://superset.apache.org/docs/developer-portal/contributing/code-review)
+- [Development How-tos](https://superset.apache.org/docs/developer-portal/contributing/howtos)
 
 Source for the Developer Portal documentation is [located here](https://github.com/apache/superset/tree/master/docs/developer_portal).

Dockerfile

@@ -18,7 +18,7 @@
 ######################################################################
 # Node stage to deal with static asset construction
 ######################################################################
-ARG PY_VER=3.11.14-slim-trixie
+ARG PY_VER=3.11.13-slim-trixie
 
 # If BUILDPLATFORM is null, set it to 'amd64' (or leave as is otherwise).
 ARG BUILDPLATFORM=${BUILDPLATFORM:-amd64}
@@ -171,8 +171,6 @@ RUN mkdir -p \
     && touch superset/static/version_info.json
 
 # Install Playwright and optionally setup headless browsers
-ENV PLAYWRIGHT_BROWSERS_PATH=/usr/local/share/playwright-browsers
-
 ARG INCLUDE_CHROMIUM="false"
 ARG INCLUDE_FIREFOX="false"
 RUN --mount=type=cache,target=${SUPERSET_HOME}/.cache/uv \

LINTING_ARCHITECTURE.md

@@ -1,121 +0,0 @@
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Superset Frontend Linting Architecture
-
-## Overview
-We use a hybrid linting approach combining OXC (fast, standard rules) with custom AST-based checks for Superset-specific patterns.
-
-## Components
-
-### 1. Primary Linter: OXC
-- **What**: Oxidation Compiler's linter (oxlint)
-- **Handles**: 95% of linting rules (standard ESLint rules, TypeScript, React, etc.)
-- **Speed**: ~50-100x faster than ESLint
-- **Config**: `oxlint.json`
-
-### 2. Custom Rule Checker
-- **What**: Node.js AST-based script
-- **Handles**: Superset-specific rules:
-  - No literal colors (use theme)
-  - No FontAwesome icons (use Icons component)
-  - No template vars in i18n
-- **Speed**: Fast enough for pre-commit
-- **Script**: `scripts/check-custom-rules.js`
-
-## Developer Workflow
-
-### Local Development
-```bash
-# Fast linting (OXC only)
-npm run lint
-
-# Full linting (OXC + custom rules)
-npm run lint:full
-
-# Auto-fix what's possible
-npm run lint-fix
-```
-
-### Pre-commit
-1. OXC runs first (via `scripts/oxlint.sh`)
-2. Custom rules check runs second (lightweight, AST-based)
-3. Both must pass for commit to succeed
-
-### CI Pipeline
-```yaml
-- name: Lint with OXC
-  run: npm run lint
-
-- name: Check custom rules
-  run: npm run check:custom-rules
-```
-
-## Why This Architecture?
-
-### ✅ Pros
-1. **No binary distribution issues** - ASF compatible
-2. **Fast performance** - OXC for bulk, lightweight script for custom
-3. **Maintainable** - Custom rules in JavaScript, not Rust
-4. **Flexible** - Can evolve as OXC adds plugin support
-5. **Cacheable** - Both OXC and Node.js are standard tools
-
-### ❌ Cons  
-1. **Two tools** - Slightly more complex than single linter
-2. **Duplicate parsing** - Files parsed twice (once by each tool)
-
-### 🔄 Migration Path
-When OXC supports JavaScript plugins:
-1. Convert `check-custom-rules.js` to OXC plugin format
-2. Consolidate back to single tool
-3. Keep same rules and developer experience
-
-## Implementation Checklist
-
-- [x] OXC for standard linting
-- [x] Pre-commit integration  
-- [ ] Custom rules script
-- [ ] Combine in npm scripts
-- [ ] Update CI pipeline
-- [ ] Developer documentation
-
-## Performance Targets
-
-| Operation | Target Time | Current |
-|-----------|------------|---------|
-| Pre-commit (changed files) | <2s | ✅ 1.5s |
-| Full lint (all files) | <10s | ✅ 8s |
-| Custom rules check | <5s | 🔄 TBD |
-
-## Caching Strategy
-
-### Local Development
-- OXC: Built-in incremental checking
-- Custom rules: Use file hash cache (similar to pytest cache)
-
-### CI
-- Cache `node_modules` (includes oxlint binary)
-- Cache custom rules results by commit hash
-- Skip unchanged files using git diff
-
-## Future Improvements
-
-1. **When OXC adds plugin support**: Migrate custom rules to OXC plugins
-2. **Consider Biome**: Another Rust-based linter with plugin support
-3. **AST sharing**: Investigate sharing AST between tools to avoid double parsing

RESOURCES/FEATURE_FLAGS.md

@@ -68,7 +68,7 @@ These features flags are **safe for production**. They have been tested and will
 
 ### Flags retained for runtime configuration
 
-Currently some of our feature flags act as dynamic configurations that can change
+Currently some of our feature flags act as dynamic configurations that can changed
 on the fly. This acts in contradiction with the typical ephemeral feature flag use case,
 where the flag is used to mature a feature, and eventually deprecated once the feature is
 solid. Eventually we'll likely refactor these under a more formal "dynamic configurations" managed

UPDATING.md

@@ -23,108 +23,6 @@ This file documents any backwards-incompatible changes in Superset and
 assists people when migrating to a new version.
 
 ## Next
-
-### MCP Service
-
-The MCP (Model Context Protocol) service enables AI assistants and automation tools to interact programmatically with Superset.
-
-#### New Features
-- MCP service infrastructure with FastMCP framework
-- Tools for dashboards, charts, datasets, SQL Lab, and instance metadata
-- Optional dependency: install with `pip install apache-superset[fastmcp]`
-- Runs as separate process from Superset web server
-- JWT-based authentication for production deployments
-
-#### New Configuration Options
-
-**Development** (single-user, local testing):
-```python
-# superset_config.py
-MCP_DEV_USERNAME = "admin"  # User for MCP authentication
-MCP_SERVICE_HOST = "localhost"
-MCP_SERVICE_PORT = 5008
-```
-
-**Production** (JWT-based, multi-user):
-```python
-# superset_config.py
-MCP_AUTH_ENABLED = True
-MCP_JWT_ISSUER = "https://your-auth-provider.com"
-MCP_JWT_AUDIENCE = "superset-mcp"
-MCP_JWT_ALGORITHM = "RS256"  # or "HS256" for shared secrets
-
-# Option 1: Use JWKS endpoint (recommended for RS256)
-MCP_JWKS_URI = "https://auth.example.com/.well-known/jwks.json"
-
-# Option 2: Use static public key (RS256)
-MCP_JWT_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----..."
-
-# Option 3: Use shared secret (HS256)
-MCP_JWT_ALGORITHM = "HS256"
-MCP_JWT_SECRET = "your-shared-secret-key"
-
-# Optional overrides
-MCP_SERVICE_HOST = "0.0.0.0"
-MCP_SERVICE_PORT = 5008
-MCP_SESSION_CONFIG = {
-    "SESSION_COOKIE_SECURE": True,
-    "SESSION_COOKIE_HTTPONLY": True,
-    "SESSION_COOKIE_SAMESITE": "Strict",
-}
-```
-
-#### Running the MCP Service
-
-```bash
-# Development
-superset mcp run --port 5008 --debug
-
-# Production
-superset mcp run --port 5008
-
-# With factory config
-superset mcp run --port 5008 --use-factory-config
-```
-
-#### Deployment Considerations
-
-The MCP service runs as a **separate process** from the Superset web server.
-
-**Important**:
-- Requires same Python environment and configuration as Superset
-- Shares database connections with main Superset app
-- Can be scaled independently from web server
-- Requires `fastmcp` package (optional dependency)
-
-**Installation**:
-```bash
-# Install with MCP support
-pip install apache-superset[fastmcp]
-
-# Or add to requirements.txt
-apache-superset[fastmcp]>=X.Y.Z
-```
-
-**Process Management**:
-Use systemd, supervisord, or Kubernetes to manage the MCP service process.
-See `superset/mcp_service/PRODUCTION.md` for deployment guides.
-
-**Security**:
-- Development: Uses `MCP_DEV_USERNAME` for single-user access
-- Production: **MUST** configure JWT authentication
-- See `superset/mcp_service/SECURITY.md` for details
-
-#### Documentation
-
-- Architecture: `superset/mcp_service/ARCHITECTURE.md`
-- Security: `superset/mcp_service/SECURITY.md`
-- Production: `superset/mcp_service/PRODUCTION.md`
-- Developer Guide: `superset/mcp_service/CLAUDE.md`
-- Quick Start: `superset/mcp_service/README.md`
-
----
-
-- [35621](https://github.com/apache/superset/pull/35621): The default hash algorithm has changed from MD5 to SHA-256 for improved security and FedRAMP compliance. This affects cache keys for thumbnails, dashboard digests, chart digests, and filter option names. Existing cached data will be invalidated upon upgrade. To opt out of this change and maintain backward compatibility, set `HASH_ALGORITHM = "md5"` in your `superset_config.py`.
 - [33055](https://github.com/apache/superset/pull/33055): Upgrades Flask-AppBuilder to 5.0.0. The AUTH_OID authentication type has been deprecated and is no longer available as an option in Flask-AppBuilder. OpenID (OID) is considered a deprecated authentication protocol - if you are using AUTH_OID, you will need to migrate to an alternative authentication method such as OAuth, LDAP, or database authentication before upgrading.
 - [35062](https://github.com/apache/superset/pull/35062): Changed the function signature of `setupExtensions` to `setupCodeOverrides` with options as arguments.
 - [34871](https://github.com/apache/superset/pull/34871): Fixed Jest test hanging issue from Ant Design v5 upgrade. MessageChannel is now mocked in test environment to prevent rc-overflow from causing Jest to hang. Test environment only - no production impact.
@@ -143,35 +41,10 @@ Note: Pillow is now a required dependency (previously optional) to support image
 - [33116](https://github.com/apache/superset/pull/33116) In Echarts Series charts (e.g. Line, Area, Bar, etc.) charts, the `x_axis_sort_series` and `x_axis_sort_series_ascending` form data items have been renamed with `x_axis_sort` and `x_axis_sort_asc`.
   There's a migration added that can potentially affect a significant number of existing charts.
 - [32317](https://github.com/apache/superset/pull/32317) The horizontal filter bar feature is now out of testing/beta development and its feature flag `HORIZONTAL_FILTER_BAR` has been removed.
-- [31590](https://github.com/apache/superset/pull/31590) Marks the beginning of intricate work around supporting dynamic Theming, and breaks support for [THEME_OVERRIDES](https://github.com/apache/superset/blob/732de4ac7fae88e29b7f123b6cbb2d7cd411b0e4/superset/config.py#L671) in favor of a new theming system based on AntD V5. Likely this will be in disrepair until settling over the 5.x lifecycle.
+- [31590](https://github.com/apache/superset/pull/31590) Marks the begining of intricate work around supporting dynamic Theming, and breaks support for [THEME_OVERRIDES](https://github.com/apache/superset/blob/732de4ac7fae88e29b7f123b6cbb2d7cd411b0e4/superset/config.py#L671) in favor of a new theming system based on AntD V5. Likely this will be in disrepair until settling over the 5.x lifecycle.
 - [32432](https://github.com/apache/superset/pull/31260) Moves the List Roles FAB view to the frontend and requires `FAB_ADD_SECURITY_API` to be enabled in the configuration and `superset init` to be executed.
 - [34319](https://github.com/apache/superset/pull/34319) Drill to Detail and Drill By is now supported in Embedded mode, and also with the `DASHBOARD_RBAC` FF. If you don't want to expose these features in Embedded / `DASHBOARD_RBAC`, make sure the roles used for Embedded / `DASHBOARD_RBAC`don't have the required permissions to perform D2D actions.
 
-### Breaking Changes
-
-#### CUSTOM_FONT_URLS removed
-
-The `CUSTOM_FONT_URLS` configuration option has been removed. Use the new per-theme `fontUrls` token in `THEME_DEFAULT` or database-managed themes instead.
-
-**Before (5.x):**
-```python
-CUSTOM_FONT_URLS = [
-    "https://fonts.example.com/myfont.css",
-]
-```
-
-**After (6.0):**
-```python
-THEME_DEFAULT = {
-    "token": {
-        "fontUrls": [
-            "https://fonts.example.com/myfont.css",
-        ],
-        # ... other tokens
-    }
-}
-```
-
 ## 5.0.0
 
 - [31976](https://github.com/apache/superset/pull/31976) Removed the `DISABLE_LEGACY_DATASOURCE_EDITOR` feature flag. The previous value of the feature flag was `True` and now the feature is permanently removed.

docker-compose.yml

@@ -137,9 +137,9 @@ services:
       - /home/superset-websocket/node_modules
       - /home/superset-websocket/dist
 
-      # Mount config file. Create your own docker/superset-websocket/config.json
-      # for custom settings, then point to it here. Do not use this example in production.
-      - ./docker/superset-websocket/config.example.json:/home/superset-websocket/config.json:ro
+      # Mounting a config file that contains a dummy secret required to boot up.
+      # do not use this docker compose in production
+      - ./docker/superset-websocket/config.json:/home/superset-websocket/config.json
     environment:
       - PORT=8080
       - REDIS_HOST=redis

docker/README.md

@@ -34,24 +34,8 @@ intended for use with local development.
 
 ### Local overrides
 
-#### Environment Variables
-
-To override environment variables locally, create a `./docker/.env-local` file (git-ignored). This file will be loaded after `.env` and can override any settings.
-
-#### Python Configuration
-
 In order to override configuration settings locally, simply make a copy of [`./docker/pythonpath_dev/superset_config_local.example`](./pythonpath_dev/superset_config_local.example)
-into `./docker/pythonpath_dev/superset_config_docker.py` (git-ignored) and fill in your overrides.
-
-#### WebSocket Configuration
-
-To customize the WebSocket server configuration, create `./docker/superset-websocket/config.json` (git-ignored) based on [`./docker/superset-websocket/config.example.json`](./superset-websocket/config.example.json).
-
-Then update the `superset-websocket`.`volumes` config to mount it.
-
-#### Docker Compose Overrides
-
-For advanced Docker Compose customization, create a `docker-compose-override.yml` file (git-ignored) to override or extend services without modifying the main compose file.
+into `./docker/pythonpath_dev/superset_config_docker.py` (git ignored) and fill in your overrides.
 
 ### Local packages
 

docker/docker-bootstrap.sh

@@ -80,16 +80,12 @@ case "${1}" in
     ;;
   app)
     echo "Starting web app (using development server)..."
-    flask run -p $PORT --reload --debugger --without-threads --host=0.0.0.0 --exclude-patterns "*/node_modules/*:*/.venv/*:*/build/*:*/__pycache__/*"
+    flask run -p $PORT --reload --debugger --without-threads --host=0.0.0.0
     ;;
   app-gunicorn)
     echo "Starting web app..."
     /usr/bin/run-server.sh
     ;;
-  mcp)
-    echo "Starting MCP service..."
-    superset mcp run --host 0.0.0.0 --port ${MCP_PORT:-5008} --debug
-    ;;
   *)
     echo "Unknown Operation!!!"
     ;;

docker/pythonpath_dev/superset_config_docker_light.py

@@ -19,7 +19,6 @@
 
 # Import all settings from the main config first
 from flask_caching.backends.filesystemcache import FileSystemCache
-
 from superset_config import *  # noqa: F403
 
 # Override caching to use simple in-memory cache instead of Redis

docker/superset-websocket/config.example.json

@@ -1,22 +0,0 @@
-{
-  "port": 8080,
-  "logLevel": "info",
-  "logToFile": false,
-  "logFilename": "app.log",
-  "statsd": {
-    "host": "127.0.0.1",
-    "port": 8125,
-    "globalTags": []
-  },
-  "redis": {
-    "port": 6379,
-    "host": "127.0.0.1",
-    "password": "",
-    "db": 0,
-    "ssl": false
-  },
-  "redisStreamPrefix": "async-events-",
-  "jwtAlgorithms": ["HS256"],
-  "jwtSecret": "CHANGE-ME-IN-PRODUCTION-GOTTA-BE-LONG-AND-SECRET",
-  "jwtCookieName": "async-token"
-}

docs/developer_portal/api/frontend.md

@@ -0,0 +1,772 @@
+---
+title: Frontend API Reference
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Frontend Extension API Reference
+
+The `@apache-superset/core` package provides comprehensive APIs for frontend extensions to interact with Apache Superset. All APIs are versioned and follow semantic versioning principles.
+
+## Core APIs
+
+### Extension Context
+
+Every extension receives a context object during activation that provides access to the extension system.
+
+```typescript
+interface ExtensionContext {
+  // Unique extension identifier
+  extensionId: string;
+
+  // Extension metadata
+  extensionPath: string;
+  extensionUri: Uri;
+
+  // Storage paths
+  globalStorageUri: Uri;
+  workspaceStorageUri: Uri;
+
+  // Subscription management
+  subscriptions: Disposable[];
+
+  // State management
+  globalState: Memento;
+  workspaceState: Memento;
+
+  // Extension-specific APIs
+  registerView(viewId: string, component: React.Component): Disposable;
+  registerCommand(commandId: string, handler: CommandHandler): Disposable;
+}
+```
+
+### Lifecycle Methods
+
+```typescript
+// Required: Called when extension is activated
+export function activate(context: ExtensionContext): void | Promise<void> {
+  console.log('Extension activated');
+}
+
+// Optional: Called when extension is deactivated
+export function deactivate(): void | Promise<void> {
+  console.log('Extension deactivated');
+}
+```
+
+## SQL Lab APIs
+
+The `sqlLab` namespace provides APIs specific to SQL Lab functionality.
+
+### Query Management
+
+```typescript
+// Get current query editor content
+sqlLab.getCurrentQuery(): string | undefined
+
+// Get active tab information
+sqlLab.getCurrentTab(): Tab | undefined
+
+// Get all open tabs
+sqlLab.getTabs(): Tab[]
+
+// Get available databases
+sqlLab.getDatabases(): Database[]
+
+// Get schemas for a database
+sqlLab.getSchemas(databaseId: number): Promise<Schema[]>
+
+// Get tables for a schema
+sqlLab.getTables(databaseId: number, schema: string): Promise<Table[]>
+
+// Insert text at cursor position
+sqlLab.insertText(text: string): void
+
+// Replace entire query
+sqlLab.replaceQuery(query: string): void
+
+// Execute current query
+sqlLab.executeQuery(): Promise<QueryResult>
+
+// Stop query execution
+sqlLab.stopQuery(queryId: string): Promise<void>
+```
+
+### Event Subscriptions
+
+```typescript
+// Query execution events
+sqlLab.onDidQueryRun(
+  listener: (event: QueryRunEvent) => void
+): Disposable
+
+sqlLab.onDidQueryComplete(
+  listener: (event: QueryCompleteEvent) => void
+): Disposable
+
+sqlLab.onDidQueryFail(
+  listener: (event: QueryFailEvent) => void
+): Disposable
+
+// Editor events
+sqlLab.onDidChangeEditorContent(
+  listener: (content: string) => void
+): Disposable
+
+sqlLab.onDidChangeActiveTab(
+  listener: (tab: Tab) => void
+): Disposable
+
+// Panel events
+sqlLab.onDidOpenPanel(
+  listener: (panel: Panel) => void
+): Disposable
+
+sqlLab.onDidClosePanel(
+  listener: (panel: Panel) => void
+): Disposable
+```
+
+### Types
+
+```typescript
+interface Tab {
+  id: string;
+  title: string;
+  query: string;
+  database: Database;
+  schema?: string;
+  isActive: boolean;
+  queryId?: string;
+  status?: 'pending' | 'running' | 'success' | 'error';
+}
+
+interface Database {
+  id: number;
+  name: string;
+  backend: string;
+  allows_subquery: boolean;
+  allows_ctas: boolean;
+  allows_cvas: boolean;
+}
+
+interface QueryResult {
+  queryId: string;
+  status: 'success' | 'error';
+  data?: any[];
+  columns?: Column[];
+  error?: string;
+  startTime: number;
+  endTime: number;
+  rows: number;
+}
+```
+
+## Commands API
+
+Register and execute commands within Superset.
+
+### Registration
+
+```typescript
+interface CommandHandler {
+  execute(...args: any[]): any | Promise<any>;
+  isEnabled?(): boolean;
+  isVisible?(): boolean;
+}
+
+// Register a command
+commands.registerCommand(
+  commandId: string,
+  handler: CommandHandler
+): Disposable
+
+// Register with metadata
+commands.registerCommand(
+  commandId: string,
+  metadata: CommandMetadata,
+  handler: (...args: any[]) => any
+): Disposable
+
+interface CommandMetadata {
+  title: string;
+  category?: string;
+  icon?: string;
+  enablement?: string;
+  when?: string;
+}
+```
+
+### Execution
+
+```typescript
+// Execute a command
+commands.executeCommand<T>(
+  commandId: string,
+  ...args: any[]
+): Promise<T>
+
+// Get all registered commands
+commands.getCommands(): Promise<string[]>
+
+// Check if command exists
+commands.hasCommand(commandId: string): boolean
+```
+
+### Built-in Commands
+
+```typescript
+// SQL Lab commands
+'sqllab.executeQuery'
+'sqllab.formatQuery'
+'sqllab.saveQuery'
+'sqllab.shareQuery'
+'sqllab.downloadResults'
+
+// Editor commands
+'editor.action.formatDocument'
+'editor.action.commentLine'
+'editor.action.findReferences'
+
+// Extension commands
+'extensions.installExtension'
+'extensions.uninstallExtension'
+'extensions.enableExtension'
+'extensions.disableExtension'
+```
+
+## UI Components
+
+Pre-built components from `@apache-superset/core` for consistent UI.
+
+### Basic Components
+
+```typescript
+import {
+  Button,
+  Input,
+  Select,
+  Checkbox,
+  Radio,
+  Switch,
+  Slider,
+  DatePicker,
+  TimePicker,
+  Tooltip,
+  Popover,
+  Modal,
+  Drawer,
+  Alert,
+  Message,
+  Notification,
+  Spin,
+  Progress
+} from '@apache-superset/core';
+```
+
+### Data Display
+
+```typescript
+import {
+  Table,
+  List,
+  Card,
+  Collapse,
+  Tabs,
+  Tag,
+  Badge,
+  Statistic,
+  Timeline,
+  Tree,
+  Empty,
+  Result
+} from '@apache-superset/core';
+```
+
+### Form Components
+
+```typescript
+import {
+  Form,
+  FormItem,
+  FormList,
+  InputNumber,
+  TextArea,
+  Upload,
+  Rate,
+  Cascader,
+  AutoComplete,
+  Mentions
+} from '@apache-superset/core';
+```
+
+## Authentication API
+
+Access authentication and user information.
+
+```typescript
+// Get current user
+authentication.getCurrentUser(): User | undefined
+
+interface User {
+  id: number;
+  username: string;
+  email: string;
+  firstName: string;
+  lastName: string;
+  roles: Role[];
+  isActive: boolean;
+  isAnonymous: boolean;
+}
+
+// Get CSRF token for API requests
+authentication.getCSRFToken(): Promise<string>
+
+// Check permissions
+authentication.hasPermission(
+  permission: string,
+  resource?: string
+): boolean
+
+// Get user preferences
+authentication.getPreferences(): UserPreferences
+
+// Update preferences
+authentication.setPreference(
+  key: string,
+  value: any
+): Promise<void>
+```
+
+## Storage API
+
+Persist data across sessions.
+
+### Global Storage
+
+```typescript
+// Shared across all workspaces
+const globalState = context.globalState;
+
+// Get value
+const value = globalState.get<T>(key: string): T | undefined
+
+// Set value
+await globalState.update(key: string, value: any): Promise<void>
+
+// Get all keys
+globalState.keys(): readonly string[]
+```
+
+### Workspace Storage
+
+```typescript
+// Specific to current workspace
+const workspaceState = context.workspaceState;
+
+// Same API as globalState
+workspaceState.get<T>(key: string): T | undefined
+workspaceState.update(key: string, value: any): Promise<void>
+workspaceState.keys(): readonly string[]
+```
+
+### Secrets Storage
+
+```typescript
+// Secure storage for sensitive data
+secrets.store(key: string, value: string): Promise<void>
+secrets.get(key: string): Promise<string | undefined>
+secrets.delete(key: string): Promise<void>
+```
+
+## Events API
+
+Subscribe to and emit custom events.
+
+```typescript
+// Create an event emitter
+const onDidChange = new EventEmitter<ChangeEvent>();
+
+// Expose as event
+export const onChange = onDidChange.event;
+
+// Fire event
+onDidChange.fire({
+  type: 'update',
+  data: newData
+});
+
+// Subscribe to event
+const disposable = onChange((event) => {
+  console.log('Changed:', event);
+});
+
+// Cleanup
+disposable.dispose();
+```
+
+## Window API
+
+Interact with the UI window.
+
+### Notifications
+
+```typescript
+// Show info message
+window.showInformationMessage(
+  message: string,
+  ...items: string[]
+): Promise<string | undefined>
+
+// Show warning
+window.showWarningMessage(
+  message: string,
+  ...items: string[]
+): Promise<string | undefined>
+
+// Show error
+window.showErrorMessage(
+  message: string,
+  ...items: string[]
+): Promise<string | undefined>
+
+// Show with options
+window.showInformationMessage(
+  message: string,
+  options: MessageOptions,
+  ...items: MessageItem[]
+): Promise<MessageItem | undefined>
+
+interface MessageOptions {
+  modal?: boolean;
+  detail?: string;
+}
+```
+
+### Input Dialogs
+
+```typescript
+// Show input box
+window.showInputBox(
+  options?: InputBoxOptions
+): Promise<string | undefined>
+
+interface InputBoxOptions {
+  title?: string;
+  prompt?: string;
+  placeHolder?: string;
+  value?: string;
+  password?: boolean;
+  validateInput?(value: string): string | null;
+}
+
+// Show quick pick
+window.showQuickPick(
+  items: string[] | QuickPickItem[],
+  options?: QuickPickOptions
+): Promise<string | QuickPickItem | undefined>
+
+interface QuickPickOptions {
+  title?: string;
+  placeHolder?: string;
+  canPickMany?: boolean;
+  matchOnDescription?: boolean;
+  matchOnDetail?: boolean;
+}
+```
+
+### Progress
+
+```typescript
+// Show progress
+window.withProgress<T>(
+  options: ProgressOptions,
+  task: (progress: Progress<{message?: string}>) => Promise<T>
+): Promise<T>
+
+interface ProgressOptions {
+  location: ProgressLocation;
+  title?: string;
+  cancellable?: boolean;
+}
+
+// Example usage
+await window.withProgress(
+  {
+    location: ProgressLocation.Notification,
+    title: "Processing",
+    cancellable: true
+  },
+  async (progress) => {
+    progress.report({ message: 'Step 1...' });
+    await step1();
+    progress.report({ message: 'Step 2...' });
+    await step2();
+  }
+);
+```
+
+## Workspace API
+
+Access workspace information and configuration.
+
+```typescript
+// Get workspace folders
+workspace.workspaceFolders: readonly WorkspaceFolder[]
+
+// Get configuration
+workspace.getConfiguration(
+  section?: string
+): WorkspaceConfiguration
+
+// Update configuration
+workspace.getConfiguration('myExtension')
+  .update('setting', value, ConfigurationTarget.Workspace)
+
+// Watch for configuration changes
+workspace.onDidChangeConfiguration(
+  listener: (e: ConfigurationChangeEvent) => void
+): Disposable
+
+// File system operations
+workspace.fs.readFile(uri: Uri): Promise<Uint8Array>
+workspace.fs.writeFile(uri: Uri, content: Uint8Array): Promise<void>
+workspace.fs.delete(uri: Uri): Promise<void>
+workspace.fs.rename(oldUri: Uri, newUri: Uri): Promise<void>
+workspace.fs.copy(source: Uri, destination: Uri): Promise<void>
+workspace.fs.createDirectory(uri: Uri): Promise<void>
+workspace.fs.readDirectory(uri: Uri): Promise<[string, FileType][]>
+workspace.fs.stat(uri: Uri): Promise<FileStat>
+```
+
+## HTTP Client API
+
+Make HTTP requests from extensions.
+
+```typescript
+import { api } from '@apache-superset/core';
+
+// GET request
+const response = await api.get('/api/v1/chart/');
+
+// POST request
+const response = await api.post('/api/v1/chart/', {
+  data: chartData
+});
+
+// PUT request
+const response = await api.put('/api/v1/chart/123', {
+  data: updatedData
+});
+
+// DELETE request
+const response = await api.delete('/api/v1/chart/123');
+
+// Custom headers
+const response = await api.get('/api/v1/chart/', {
+  headers: {
+    'X-Custom-Header': 'value'
+  }
+});
+
+// Query parameters
+const response = await api.get('/api/v1/chart/', {
+  params: {
+    page: 1,
+    page_size: 20
+  }
+});
+```
+
+## Theming API
+
+Access and customize theme settings.
+
+```typescript
+// Get current theme
+theme.getActiveTheme(): Theme
+
+interface Theme {
+  name: string;
+  isDark: boolean;
+  colors: ThemeColors;
+  typography: Typography;
+  spacing: Spacing;
+}
+
+// Listen for theme changes
+theme.onDidChangeTheme(
+  listener: (theme: Theme) => void
+): Disposable
+
+// Get theme colors
+const colors = theme.colors;
+colors.primary
+colors.success
+colors.warning
+colors.error
+colors.info
+colors.text
+colors.background
+colors.border
+```
+
+## Disposable Pattern
+
+Manage resource cleanup consistently.
+
+```typescript
+interface Disposable {
+  dispose(): void;
+}
+
+// Create a disposable
+class MyDisposable implements Disposable {
+  dispose() {
+    // Cleanup logic
+  }
+}
+
+// Combine disposables
+const composite = Disposable.from(
+  disposable1,
+  disposable2,
+  disposable3
+);
+
+// Dispose all at once
+composite.dispose();
+
+// Use in extension
+export function activate(context: ExtensionContext) {
+  // All disposables added here are cleaned up on deactivation
+  context.subscriptions.push(
+    registerCommand(...),
+    registerView(...),
+    onDidChange(...)
+  );
+}
+```
+
+## Type Definitions
+
+Complete TypeScript definitions are available:
+
+```typescript
+import type {
+  ExtensionContext,
+  Disposable,
+  Event,
+  EventEmitter,
+  Uri,
+  Command,
+  QuickPickItem,
+  InputBoxOptions,
+  Progress,
+  CancellationToken
+} from '@apache-superset/core';
+```
+
+## Version Compatibility
+
+The API follows semantic versioning:
+
+```typescript
+// Check API version
+const version = superset.version;
+
+// Version components
+version.major // Breaking changes
+version.minor // New features
+version.patch // Bug fixes
+
+// Check minimum version
+if (version.major < 1) {
+  throw new Error('Requires Superset API v1.0.0 or higher');
+}
+```
+
+## Migration Guide
+
+### From v0.x to v1.0
+
+```typescript
+// Before (v0.x)
+sqlLab.runQuery(query);
+
+// After (v1.0)
+sqlLab.executeQuery();
+
+// Before (v0.x)
+core.registerPanel(id, component);
+
+// After (v1.0)
+context.registerView(id, component);
+```
+
+## Best Practices
+
+### Error Handling
+
+```typescript
+export async function activate(context: ExtensionContext) {
+  try {
+    await initializeExtension();
+  } catch (error) {
+    console.error('Failed to initialize:', error);
+    window.showErrorMessage(
+      `Extension failed to activate: ${error.message}`
+    );
+  }
+}
+```
+
+### Resource Management
+
+```typescript
+// Always use disposables
+const disposables: Disposable[] = [];
+
+disposables.push(
+  commands.registerCommand(...),
+  sqlLab.onDidQueryRun(...),
+  workspace.onDidChangeConfiguration(...)
+);
+
+// Cleanup in deactivate
+export function deactivate() {
+  disposables.forEach(d => d.dispose());
+}
+```
+
+### Type Safety
+
+```typescript
+// Use type guards
+function isDatabase(obj: any): obj is Database {
+  return obj && typeof obj.id === 'number' && typeof obj.name === 'string';
+}
+
+// Use generics
+function getValue<T>(key: string, defaultValue: T): T {
+  return context.globalState.get(key) ?? defaultValue;
+}
+```

docs/developer_portal/architecture/overview.md

@@ -0,0 +1,194 @@
+---
+title: Extension Architecture
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Superset Extension Architecture
+
+Apache Superset's extension architecture enables developers to enhance and customize the platform without modifying the core codebase. Inspired by the successful VS Code Extensions model, this architecture provides well-defined, versioned APIs and clear contribution points that allow the community to build upon and extend Superset's functionality.
+
+## Core Concepts
+
+### Extensions vs Plugins
+
+We use the term "extensions" rather than "plugins" to better convey the idea of enhancing and expanding Superset's core capabilities in a modular and integrated way. Extensions can add new features, modify existing behavior, and integrate deeply with the host application through well-defined APIs.
+
+### Lean Core Philosophy
+
+Superset's core remains minimal, with many features delegated to extensions. Built-in features are implemented using the same APIs available to external extension authors, ensuring consistency and validating the extension architecture through real-world usage.
+
+## Architecture Overview
+
+The extension architecture consists of several key components:
+
+### Core Packages
+
+#### @apache-superset/core (Frontend)
+Provides essential building blocks for extensions:
+- Shared UI components
+- Utility functions
+- Type definitions
+- Frontend APIs for interacting with the host
+
+#### apache-superset-core (Backend)
+Exposes backend functionality:
+- Database access APIs
+- Security models
+- REST API extensions
+- SQLAlchemy models and utilities
+
+### Extension CLI
+
+The `apache-superset-extensions-cli` package provides commands for:
+- Scaffolding new extension projects
+- Building and bundling extensions
+- Development workflows with hot-reload
+- Packaging extensions for distribution
+
+### Host Application
+
+Superset acts as the host, providing:
+- Extension registration and management
+- Dynamic loading of extension assets
+- API implementation for extensions
+- Lifecycle management (activation/deactivation)
+
+## Extension Points
+
+Extensions can contribute to various parts of Superset:
+
+### SQL Lab Extensions
+- Custom panels (left, right, bottom)
+- Editor enhancements
+- Query processors
+- Autocomplete providers
+- Execution plan visualizers
+
+### Dashboard Extensions (Future)
+- Custom widget types
+- Filter components
+- Interaction handlers
+
+### Chart Extensions (Future)
+- New visualization types
+- Data transformers
+- Export formats
+
+## Technical Foundation
+
+### Module Federation
+
+Frontend extensions leverage Webpack Module Federation for dynamic loading:
+- Extensions are built independently
+- Dependencies are shared with the host
+- No rebuild of Superset required
+- Runtime loading of extension assets
+
+### API Versioning
+
+All public APIs follow semantic versioning:
+- Breaking changes require major version bumps
+- Extensions declare compatibility requirements
+- Backward compatibility maintained within major versions
+
+### Security Model
+
+- Extensions disabled by default (require `ENABLE_EXTENSIONS` flag)
+- Built-in extensions follow same security standards as core
+- External extensions run in same context as host (sandboxing planned)
+- Administrators responsible for vetting third-party extensions
+
+## Development Workflow
+
+1. **Initialize**: Use CLI to scaffold new extension
+2. **Develop**: Work with hot-reload in development mode
+3. **Build**: Bundle frontend and backend assets
+4. **Package**: Create `.supx` distribution file
+5. **Deploy**: Upload through API or management UI
+
+## Example: Dataset References Extension
+
+A practical example demonstrating the architecture:
+
+```typescript
+// Frontend activation
+export function activate(context) {
+  // Register a new SQL Lab panel
+  const panel = core.registerView('dataset_references.main',
+    <DatasetReferencesPanel />
+  );
+
+  // Listen to query changes
+  const listener = sqlLab.onDidQueryRun(editor => {
+    // Analyze query and update panel
+  });
+
+  // Cleanup on deactivation
+  context.subscriptions.push(panel, listener);
+}
+```
+
+```python
+# Backend API extension
+from superset_core.api import rest_api
+from .api import DatasetReferencesAPI
+
+# Register custom REST endpoints
+rest_api.add_extension_api(DatasetReferencesAPI)
+```
+
+## Best Practices
+
+### Extension Design
+- Keep extensions focused on specific functionality
+- Use versioned APIs for stability
+- Handle cleanup properly on deactivation
+- Follow Superset's coding standards
+
+### Performance
+- Lazy load assets when possible
+- Minimize bundle sizes
+- Share dependencies with host
+- Cache expensive operations
+
+### Compatibility
+- Declare API version requirements
+- Test across Superset versions
+- Provide migration guides for breaking changes
+- Document compatibility clearly
+
+## Future Roadmap
+
+Planned enhancements include:
+- JavaScript sandboxing for untrusted extensions
+- Extension marketplace and registry
+- Inter-extension communication
+- Advanced theming capabilities
+- Backend hot-reload without restart
+
+## Getting Started
+
+Ready to build your first extension? Check out:
+- [Extension Project Structure](/developer_portal/extensions/extension-project-structure)
+- [API Reference](/developer_portal/api/frontend)
+- [CLI Documentation](/developer_portal/cli/overview)
+- [Frontend Contribution Types](/developer_portal/extensions/frontend-contribution-types)

docs/developer_portal/capabilities/common-capabilities.md

@@ -0,0 +1,55 @@
+---
+title: Common Plugin Capabilities
+sidebar_position: 2
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Common Plugin Capabilities
+
+🚧 **Coming Soon** 🚧
+
+Explore the shared functionality and common patterns available to all Superset plugins.
+
+## Topics to be covered:
+
+- Plugin lifecycle hooks (initialization, activation, deactivation)
+- Accessing Superset's core services and APIs
+- State management and data persistence
+- Event handling and plugin communication
+- Internationalization (i18n) support
+- Error handling and logging
+- Plugin configuration management
+- Accessing user context and permissions
+- Working with datasets and queries
+- Plugin metadata and manifests
+
+## Core Services Available
+
+- **API Client** - HTTP client for backend communication
+- **State Store** - Redux store access
+- **Theme Provider** - Access to current theme settings
+- **User Context** - Current user information and permissions
+- **Dataset Service** - Working with data sources
+- **Chart Service** - Chart rendering utilities
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/capabilities/extending-workbench.md

@@ -0,0 +1,62 @@
+---
+title: Extending the Workbench
+sidebar_position: 4
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Extending the Workbench
+
+🚧 **Coming Soon** 🚧
+
+Discover how to extend Superset's main interface and workbench with custom components and functionality.
+
+## Topics to be covered:
+
+- Adding custom menu items and navigation
+- Creating custom dashboard components
+- Extending the SQL Lab interface
+- Adding custom sidebar panels
+- Creating floating panels and modals
+- Integrating with the command palette
+- Custom toolbar buttons and actions
+- Workspace state management
+- Plugin-specific keyboard shortcuts
+- Context menu extensions
+
+## Extension Points
+
+- **Main navigation** - Top-level menu items
+- **Dashboard builder** - Custom components and layouts
+- **SQL Lab** - Query editor extensions
+- **Chart explorer** - Visualization building tools
+- **Settings panels** - Configuration interfaces
+- **Data source explorer** - Database navigation
+
+## UI Integration Patterns
+
+- React component composition
+- Portal-based rendering
+- Event-driven UI updates
+- Responsive layout adaptation
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/capabilities/overview.md

@@ -0,0 +1,53 @@
+---
+title: Plugin Capabilities Overview
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Plugin Capabilities Overview
+
+🚧 **Coming Soon** 🚧
+
+This section provides a comprehensive overview of what Superset plugins can do and how they integrate with the core platform.
+
+## Topics to be covered:
+
+- Plugin architecture and lifecycle
+- Available extension points
+- Core APIs and services
+- Plugin communication patterns
+- Configuration and settings management
+- Plugin permissions and security
+- Performance considerations
+- Best practices for plugin development
+
+## Plugin Types
+
+Superset supports several types of plugins:
+- **Visualization plugins** - Custom chart types and data visualizations
+- **Database connectors** - New data source integrations
+- **UI extensions** - Custom dashboard components and interfaces
+- **Theme plugins** - Custom styling and branding
+- **Filter plugins** - Custom filter components
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/capabilities/theming.md

@@ -0,0 +1,61 @@
+---
+title: Theming and Styling
+sidebar_position: 3
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Theming and Styling
+
+🚧 **Coming Soon** 🚧
+
+Learn how to create custom themes and style your plugins to match Superset's design system.
+
+## Topics to be covered:
+
+- Understanding Superset's theme architecture
+- Using the theme provider in plugins
+- Creating custom color palettes
+- Responsive design considerations
+- Dark mode and light mode support
+- Customizing chart colors and styling
+- Brand customization and white-labeling
+- CSS-in-JS best practices
+- Working with Ant Design components
+- Accessibility in custom themes
+
+## Theme Structure
+
+- **Color tokens** - Primary, secondary, and semantic colors
+- **Typography** - Font families, sizes, and weights
+- **Spacing** - Grid system and layout tokens
+- **Component styles** - Default component appearances
+- **Chart themes** - Color schemes for visualizations
+
+## Supported Theming APIs
+
+- Theme provider context
+- CSS custom properties
+- Emotion/styled-components integration
+- Chart color palette API
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/cli/overview.md

@@ -0,0 +1,578 @@
+---
+title: Extension CLI
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Superset Extension CLI
+
+The `apache-superset-extensions-cli` package provides command-line tools for creating, developing, and packaging Apache Superset extensions. It streamlines the entire extension development workflow from initialization to deployment.
+
+## Installation
+
+Install the CLI globally using pip:
+
+```bash
+pip install apache-superset-extensions-cli
+```
+
+Or install locally in your project:
+
+```bash
+pip install --user apache-superset-extensions-cli
+```
+
+Verify installation:
+
+```bash
+superset-extensions --version
+# Output: apache-superset-extensions-cli version 1.0.0
+```
+
+## Commands Overview
+
+| Command | Description |
+|---------|-------------|
+| `init` | Create a new extension project |
+| `dev` | Start development mode with hot reload |
+| `build` | Build extension assets for production |
+| `bundle` | Package extension into a .supx file |
+| `validate` | Validate extension metadata and structure |
+| `publish` | Publish extension to registry (future) |
+
+## Command Reference
+
+### init
+
+Creates a new extension project with the standard structure and boilerplate code.
+
+```bash
+superset-extensions init [options] <extension-name>
+```
+
+#### Options
+
+- `--type, -t <type>` - Extension type: `full` (default), `frontend-only`, `backend-only`
+- `--template <template>` - Project template: `default`, `sql-lab`, `dashboard`, `chart`
+- `--author <name>` - Extension author name
+- `--description <desc>` - Extension description
+- `--license <license>` - License identifier (default: Apache-2.0)
+- `--superset-version <version>` - Minimum Superset version (default: 4.0.0)
+- `--skip-install` - Skip installing dependencies
+- `--use-typescript` - Use TypeScript for frontend (default: true)
+- `--use-npm` - Use npm instead of yarn
+
+#### Examples
+
+```bash
+# Create a basic extension
+superset-extensions init my-extension
+
+# Create a SQL Lab focused extension
+superset-extensions init query-optimizer --template sql-lab
+
+# Create frontend-only extension
+superset-extensions init custom-viz --type frontend-only
+
+# Create with metadata
+superset-extensions init data-quality \
+  --author "Jane Doe" \
+  --description "Data quality monitoring for SQL Lab"
+```
+
+#### Generated Structure
+
+```
+my-extension/
+├── extension.json          # Extension metadata
+├── frontend/              # Frontend source code
+│   ├── src/
+│   │   ├── index.tsx     # Main entry point
+│   │   └── components/   # React components
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── webpack.config.js
+├── backend/               # Backend source code
+│   ├── src/
+│   │   └── my_extension/
+│   │       ├── __init__.py
+│   │       └── api.py
+│   ├── tests/
+│   └── requirements.txt
+├── README.md
+└── .gitignore
+```
+
+### dev
+
+Starts development mode with automatic rebuilding and hot reload.
+
+```bash
+superset-extensions dev [options]
+```
+
+#### Options
+
+- `--port, -p <port>` - Development server port (default: 9001)
+- `--host <host>` - Development server host (default: localhost)
+- `--watch-backend` - Also watch backend files (default: true)
+- `--watch-frontend` - Also watch frontend files (default: true)
+- `--no-open` - Don't open browser automatically
+- `--superset-url <url>` - Superset instance URL (default: http://localhost:8088)
+- `--verbose` - Enable verbose logging
+
+#### Examples
+
+```bash
+# Start development mode
+superset-extensions dev
+
+# Use custom port
+superset-extensions dev --port 9002
+
+# Connect to remote Superset
+superset-extensions dev --superset-url https://superset.example.com
+```
+
+#### Development Workflow
+
+1. **Start the dev server:**
+```bash
+superset-extensions dev
+```
+
+2. **Configure Superset** (`superset_config.py`):
+```python
+LOCAL_EXTENSIONS = [
+    "/path/to/your/extension"
+]
+ENABLE_EXTENSIONS = True
+```
+
+3. **Start Superset:**
+```bash
+superset run -p 8088 --with-threads --reload
+```
+
+The extension will automatically reload when you make changes.
+
+### build
+
+Builds extension assets for production deployment.
+
+```bash
+superset-extensions build [options]
+```
+
+#### Options
+
+- `--mode <mode>` - Build mode: `production` (default), `development`
+- `--analyze` - Generate bundle analysis report
+- `--source-maps` - Generate source maps
+- `--minify` - Minify output (default: true in production)
+- `--output, -o <dir>` - Output directory (default: dist)
+- `--clean` - Clean output directory before build
+- `--parallel` - Build frontend and backend in parallel
+
+#### Examples
+
+```bash
+# Production build
+superset-extensions build
+
+# Development build with source maps
+superset-extensions build --mode development --source-maps
+
+# Analyze bundle size
+superset-extensions build --analyze
+
+# Custom output directory
+superset-extensions build --output build
+```
+
+#### Build Output
+
+```
+dist/
+├── manifest.json          # Build manifest
+├── frontend/
+│   ├── remoteEntry.[hash].js
+│   ├── [name].[hash].js
+│   └── assets/
+└── backend/
+    └── my_extension/
+        ├── __init__.py
+        └── *.py
+```
+
+### bundle
+
+Packages the built extension into a distributable `.supx` file.
+
+```bash
+superset-extensions bundle [options]
+```
+
+#### Options
+
+- `--output, -o <file>` - Output filename (default: `{name}-{version}.supx`)
+- `--sign` - Sign the bundle (requires configured keys)
+- `--compression <level>` - Compression level 0-9 (default: 6)
+- `--exclude <patterns>` - Files to exclude (comma-separated)
+- `--include-dev-deps` - Include development dependencies
+
+#### Examples
+
+```bash
+# Create bundle
+superset-extensions bundle
+
+# Custom output name
+superset-extensions bundle --output my-extension-latest.supx
+
+# Signed bundle
+superset-extensions bundle --sign
+
+# Exclude test files
+superset-extensions bundle --exclude "**/*.test.js,**/*.spec.ts"
+```
+
+#### Bundle Structure
+
+The `.supx` file is a ZIP archive containing:
+
+```
+my-extension-1.0.0.supx
+├── manifest.json
+├── extension.json
+├── frontend/
+│   └── dist/
+└── backend/
+    └── src/
+```
+
+### validate
+
+Validates extension structure, metadata, and compatibility.
+
+```bash
+superset-extensions validate [options]
+```
+
+#### Options
+
+- `--strict` - Enable strict validation
+- `--fix` - Auto-fix correctable issues
+- `--check-deps` - Validate dependencies
+- `--check-security` - Run security checks
+
+#### Examples
+
+```bash
+# Basic validation
+superset-extensions validate
+
+# Strict mode with auto-fix
+superset-extensions validate --strict --fix
+
+# Full validation
+superset-extensions validate --check-deps --check-security
+```
+
+#### Validation Checks
+
+- Extension metadata completeness
+- File structure conformity
+- API version compatibility
+- Dependency security vulnerabilities
+- Code quality standards
+- Bundle size limits
+
+## Configuration File
+
+Create `.superset-extension.json` for project-specific settings:
+
+```json
+{
+  "build": {
+    "mode": "production",
+    "sourceMaps": true,
+    "analyze": false,
+    "parallel": true
+  },
+  "dev": {
+    "port": 9001,
+    "host": "localhost",
+    "autoOpen": true
+  },
+  "bundle": {
+    "compression": 6,
+    "sign": false,
+    "exclude": [
+      "**/*.test.*",
+      "**/*.spec.*",
+      "**/tests/**"
+    ]
+  },
+  "validation": {
+    "strict": true,
+    "autoFix": true
+  }
+}
+```
+
+## Environment Variables
+
+Configure CLI behavior using environment variables:
+
+```bash
+# Superset connection
+export SUPERSET_URL=http://localhost:8088
+export SUPERSET_USERNAME=admin
+export SUPERSET_PASSWORD=admin
+
+# Development settings
+export EXTENSION_DEV_PORT=9001
+export EXTENSION_DEV_HOST=localhost
+
+# Build settings
+export EXTENSION_BUILD_MODE=production
+export EXTENSION_SOURCE_MAPS=true
+
+# Registry settings (future)
+export EXTENSION_REGISTRY_URL=https://registry.superset.apache.org
+export EXTENSION_REGISTRY_TOKEN=your-token
+```
+
+## Advanced Usage
+
+### Custom Templates
+
+Create custom project templates:
+
+```bash
+# Use custom template
+superset-extensions init my-ext --template https://github.com/user/template
+
+# Use local template
+superset-extensions init my-ext --template ./my-template
+```
+
+### CI/CD Integration
+
+#### GitHub Actions
+
+```yaml
+name: Build Extension
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+
+      - name: Setup Node
+        uses: actions/setup-node@v2
+        with:
+          node-version: '16'
+
+      - name: Install CLI
+        run: pip install apache-superset-extensions-cli
+
+      - name: Install dependencies
+        run: |
+          npm install --prefix frontend
+          pip install -r backend/requirements.txt
+
+      - name: Validate
+        run: superset-extensions validate --strict
+
+      - name: Build
+        run: superset-extensions build --mode production
+
+      - name: Bundle
+        run: superset-extensions bundle
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: extension-bundle
+          path: '*.supx'
+```
+
+### Automated Deployment
+
+Deploy extensions automatically:
+
+```bash
+#!/bin/bash
+# deploy.sh
+
+# Build and bundle
+superset-extensions build --mode production
+superset-extensions bundle --sign
+
+# Upload to Superset instance
+BUNDLE=$(ls *.supx | head -1)
+curl -X POST "$SUPERSET_URL/api/v1/extensions/import/" \
+  -H "Authorization: Bearer $SUPERSET_TOKEN" \
+  -F "bundle=@$BUNDLE"
+
+# Verify deployment
+curl "$SUPERSET_URL/api/v1/extensions/" \
+  -H "Authorization: Bearer $SUPERSET_TOKEN"
+```
+
+### Multi-Extension Projects
+
+Manage multiple extensions in one repository:
+
+```bash
+# Initialize multiple extensions
+superset-extensions init extensions/viz-plugin --type frontend-only
+superset-extensions init extensions/sql-optimizer --template sql-lab
+superset-extensions init extensions/auth-provider --type backend-only
+
+# Build all extensions
+for dir in extensions/*/; do
+  (cd "$dir" && superset-extensions build)
+done
+
+# Bundle all extensions
+for dir in extensions/*/; do
+  (cd "$dir" && superset-extensions bundle)
+done
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Port already in use
+
+```bash
+# Error: Port 9001 is already in use
+
+# Solution: Use a different port
+superset-extensions dev --port 9002
+```
+
+#### Module not found
+
+```bash
+# Error: Cannot find module '@apache-superset/core'
+
+# Solution: Ensure dependencies are installed
+npm install --prefix frontend
+```
+
+#### Build failures
+
+```bash
+# Check Node and Python versions
+node --version  # Should be 16+
+python --version  # Should be 3.9+
+
+# Clear cache and rebuild
+rm -rf dist node_modules frontend/node_modules
+npm install --prefix frontend
+superset-extensions build --clean
+```
+
+#### Bundle too large
+
+```bash
+# Warning: Bundle size exceeds recommended limit
+
+# Solution: Analyze and optimize
+superset-extensions build --analyze
+
+# Exclude unnecessary files
+superset-extensions bundle --exclude "**/*.map,**/*.test.*"
+```
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+# Set debug environment variable
+export DEBUG=superset-extensions:*
+
+# Or use verbose flag
+superset-extensions dev --verbose
+superset-extensions build --verbose
+```
+
+### Getting Help
+
+```bash
+# General help
+superset-extensions --help
+
+# Command-specific help
+superset-extensions init --help
+superset-extensions dev --help
+
+# Version information
+superset-extensions --version
+```
+
+## Best Practices
+
+### Development
+
+1. **Use TypeScript** for type safety
+2. **Follow the style guide** for consistency
+3. **Write tests** for critical functionality
+4. **Document your code** with JSDoc/docstrings
+5. **Use development mode** for rapid iteration
+
+### Building
+
+1. **Optimize bundle size** - analyze and tree-shake
+2. **Generate source maps** for debugging
+3. **Validate before building** to catch issues early
+4. **Use production mode** for final builds
+5. **Clean build directory** to avoid stale files
+
+### Deployment
+
+1. **Sign your bundles** for security
+2. **Version properly** using semantic versioning
+3. **Test in staging** before production deployment
+4. **Document breaking changes** in CHANGELOG
+5. **Provide migration guides** for major updates
+
+## Resources
+
+- [Extension Architecture](/developer_portal/architecture/overview)
+- [API Reference](/developer_portal/api/frontend)
+- [Frontend Contribution Types](/developer_portal/extensions/frontend-contribution-types)
+- [GitHub Repository](https://github.com/apache/superset)
+- [Community Forum](https://github.com/apache/superset/discussions)

docs/developer_portal/coding-guidelines/overview.md

@@ -0,0 +1,44 @@
+---
+title: Coding Guidelines Overview
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Coding Guidelines Overview
+
+🚧 **Coming Soon** 🚧
+
+Best practices and coding standards for Apache Superset development.
+
+## Topics to be covered:
+
+- General coding principles
+- Code organization
+- Error handling
+- Performance considerations
+- Security best practices
+- Testing requirements
+- Documentation standards
+- Commit message conventions
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/contributing/code-review.md

@@ -327,9 +327,9 @@ stats.sort_stats('cumulative').print_stats(10)
 ## Resources
 
 ### Internal
-- [Coding Guidelines](../guidelines/design-guidelines)
+- [Coding Guidelines](../coding-guidelines/overview)
 - [Testing Guide](../testing/overview)
-- [Extension Architecture](../extensions/architecture)
+- [Architecture Overview](../architecture/overview)
 
 ### External
 - [Google's Code Review Guide](https://google.github.io/eng-practices/review/)

docs/developer_portal/contributing/overview.md

@@ -1,5 +1,5 @@
 ---
-title: Overview
+title: Contributing Overview
 sidebar_position: 1
 ---
 
@@ -22,7 +22,7 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Contributing
+# Contributing to Apache Superset
 
 Superset is an [Apache Software foundation](https://www.apache.org/theapacheway/index.html) project.
 The core contributors (or committers) to Superset communicate primarily in the following channels (which can be joined by anyone):

docs/developer_portal/contributing/submitting-pr.md

@@ -35,7 +35,7 @@ Learn how to create and submit high-quality pull requests to Apache Superset.
 - [ ] You've found or created an issue to work on
 
 ### PR Readiness Checklist
-- [ ] Code follows [coding guidelines](../guidelines/design-guidelines)
+- [ ] Code follows [coding guidelines](../coding-guidelines/overview)
 - [ ] Tests are passing locally
 - [ ] Linting passes (`pre-commit run --all-files`)
 - [ ] Documentation is updated if needed

docs/developer_portal/extensions/architectural-principles.md

@@ -0,0 +1,36 @@
+---
+title: Architectural Principles
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Architectural Principles
+
+Realizing this vision requires a strong architectural foundation. To ensure the resulting system is robust, maintainable, and adaptable, we have defined a set of architectural principles that will guide the design and implementation of the changes. These principles serve as the basis for all technical decisions and help create an environment where extensions can be developed safely and predictably, while minimizing technical debt and fragmentation.
+
+The architectural principles guiding this proposal include:
+
+1. **Lean core**: Superset's core should remain as minimal as possible, with many features and capabilities delegated to extensions. Wherever possible, built-in features should be implemented using the same APIs and extension mechanisms available to external extension authors. This approach reduces maintenance burden and complexity in the core application, encourages modularity, and allows the community to innovate and iterate on features independently of the main codebase.
+2. **Explicit contribution points**: All extension points must be clearly defined and documented, so extension authors know exactly where and how they can interact with the host system. Each extension must also declare its capabilities in a metadata file, enabling the host to manage the extension lifecycle and provide a consistent user experience.
+3. **Versioned and stable APIs**: Public interfaces for extensions should be versioned and follow semantic versioning, allowing for safe evolution and backward compatibility.
+4. **Lazy loading and activation**: Extensions should be loaded and activated only when needed, minimizing performance overhead and resource consumption.
+5. **Composability and reuse**: The architecture should encourage the reuse of extension points and patterns across different modules, promoting consistency and reducing duplication.
+6. **Community-driven evolution**: The system should be designed to evolve based on real-world feedback and contributions, allowing new extension points and capabilities to be added as needs emerge.

docs/developer_portal/extensions/architecture.md

@@ -1,253 +0,0 @@
----
-title: Architecture
-sidebar_position: 3
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Architecture
-
-Apache Superset's extension system is designed to enable powerful customization while maintaining stability, security, and performance. This page explains the architectural principles, system design, and technical mechanisms that make the extension ecosystem possible.
-
-## Architectural Principles
-
-The extension architecture is built on six core principles that guide all technical decisions and ensure extensions can be developed safely and predictably:
-
-### 1. Lean Core
-
-Superset's core should remain minimal, with many features delegated to extensions. Built-in features use the same APIs and extension mechanisms available to external developers. This approach:
-- Reduces maintenance burden and complexity
-- Encourages modularity
-- Allows the community to innovate independently of the main codebase
-
-### 2. Explicit Contribution Points
-
-All extension points are clearly defined and documented. Extension authors know exactly where and how they can interact with the host system. Each extension declares its capabilities in a metadata file, enabling the host to:
-- Manage the extension lifecycle
-- Provide a consistent user experience
-- Validate extension compatibility
-
-### 3. Versioned and Stable APIs
-
-Public interfaces for extensions follow semantic versioning, allowing for:
-- Safe evolution of the platform
-- Backward compatibility
-- Clear upgrade paths for extension authors
-
-### 4. Lazy Loading and Activation
-
-Extensions are loaded and activated only when needed, which:
-- Minimizes performance overhead
-- Reduces resource consumption
-- Improves startup time
-
-### 5. Composability and Reuse
-
-The architecture encourages reusing extension points and patterns across different modules, promoting:
-- Consistency across extensions
-- Reduced duplication
-- Shared best practices
-
-### 6. Community-Driven Evolution
-
-The system evolves based on real-world feedback and contributions. New extension points and capabilities are added as needs emerge, ensuring the platform remains relevant and flexible.
-
-## System Overview
-
-The extension architecture is built around three main components that work together to create a flexible, maintainable ecosystem:
-
-### Core Packages
-
-Two core packages provide the foundation for extension development:
-
-**Frontend: `@apache-superset/core`**
-
-This package provides essential building blocks for frontend extensions and the host application:
-- Shared UI components
-- Utility functions
-- APIs and hooks
-- Type definitions
-
-By centralizing these resources, both extensions and built-in features use the same APIs, ensuring consistency, type safety, and a seamless user experience. The package is versioned to support safe platform evolution while maintaining compatibility.
-
-**Backend: `apache-superset-core`**
-
-This package exposes key classes and APIs for backend extensions:
-- Database connectors
-- API extensions
-- Security manager customization
-- Core utilities and models
-
-It includes dependencies on critical libraries like Flask-AppBuilder and SQLAlchemy, and follows semantic versioning for compatibility and stability.
-
-### Developer Tools
-
-**`apache-superset-extensions-cli`**
-
-The CLI provides comprehensive commands for extension development:
-- Project scaffolding
-- Code generation
-- Building and bundling
-- Packaging for distribution
-
-By standardizing these processes, the CLI ensures extensions are built consistently, remain compatible with evolving versions of Superset, and follow best practices.
-
-### Host Application
-
-The Superset host application serves as the runtime environment for extensions:
-
-**Extension Management**
-- Exposes `/api/v1/extensions` endpoint for registration and management
-- Provides a dedicated UI for managing extensions
-- Stores extension metadata in the `extensions` database table
-
-**Extension Storage**
-
-The extensions table contains:
-- Extension name, version, and author
-- Contributed features and exposed modules
-- Metadata and configuration
-- Built frontend and/or backend code
-
-### Architecture Diagram
-
-The following diagram illustrates how these components work together:
-
-<img width="955" height="586" alt="Extension System Architecture" src="https://github.com/user-attachments/assets/cc2a41df-55a4-48c8-b056-35f7a1e567c6" />
-
-The diagram shows:
-1. **Extension projects** depend on core packages for development
-2. **Core packages** provide APIs and type definitions
-3. **The host application** implements the APIs and manages extensions
-4. **Extensions** integrate seamlessly with the host through well-defined interfaces
-
-### Extension Dependencies
-
-Extensions can depend on any combination of packages based on their needs. For example:
-
-**Frontend-only extension** (e.g., a custom chart type):
-- Depends on `@apache-superset/core` for UI components and React APIs
-
-**Full-stack extension** (e.g., a custom SQL editor with new API endpoints):
-- Depends on `@apache-superset/core` for frontend components
-- Depends on `apache-superset-core` for backend APIs and models
-
-This modular approach allows extension authors to choose exactly what they need while promoting consistency and reusability.
-
-## Dynamic Module Loading
-
-One of the most sophisticated aspects of the extension architecture is how frontend code is dynamically loaded at runtime using Webpack's Module Federation.
-
-### Module Federation
-
-The architecture leverages Webpack's Module Federation to enable dynamic loading of frontend assets. This allows extensions to be built independently from Superset.
-
-### How It Works
-
-**Extension Configuration**
-
-Extensions configure Webpack to expose their entry points:
-
-``` typescript
-new ModuleFederationPlugin({
-  name: 'my_extension',
-  filename: 'remoteEntry.[contenthash].js',
-  exposes: {
-    './index': './src/index.tsx',
-  },
-  externalsType: 'window',
-  externals: {
-    '@apache-superset/core': 'superset',
-  },
-  shared: {
-    react: { singleton: true },
-    'react-dom': { singleton: true },
-    'antd-v5': { singleton: true }
-  }
-})
-```
-
-This configuration does several important things:
-
-**`exposes`** - Declares which modules are available to the host application. The extension makes `./index` available as its entry point.
-
-**`externals` and `externalsType`** - Tell Webpack that when the extension imports `@apache-superset/core`, it should use `window.superset` at runtime instead of bundling its own copy. This ensures extensions use the host's implementation of shared packages.
-
-**`shared`** - Prevents duplication of common libraries like React and Ant Design. The `singleton: true` setting ensures only one instance of each library exists, avoiding version conflicts and reducing bundle size.
-
-### Runtime Resolution
-
-The following diagram illustrates the module loading process:
-
-<img width="913" height="558" alt="Module Federation Flow" src="https://github.com/user-attachments/assets/e5e4d2ae-e8b5-4d17-a2a1-3667c65f25ca" />
-
-Here's what happens at runtime:
-
-1. **Extension Registration**: When an extension is registered, Superset stores its remote entry URL
-2. **Dynamic Loading**: When the extension is activated, the host fetches the remote entry file
-3. **Module Resolution**: The extension imports `@apache-superset/core`, which resolves to `window.superset`
-4. **Execution**: The extension code runs with access to the host's APIs and shared dependencies
-
-### Host API Setup
-
-On the Superset side, the APIs are mapped to `window.superset` during application bootstrap:
-
-``` typescript
-import * as supersetCore from '@apache-superset/core';
-import {
-  authentication,
-  core,
-  commands,
-  environment,
-  extensions,
-  sqlLab,
-} from 'src/extensions';
-
-export default function setupExtensionsAPI() {
-  window.superset = {
-    ...supersetCore,
-    authentication,
-    core,
-    commands,
-    environment,
-    extensions,
-    sqlLab,
-  };
-}
-```
-
-This function runs before any extensions are loaded, ensuring the APIs are available when extensions import from `@apache-superset/core`.
-
-### Benefits
-
-This architecture provides several key benefits:
-
-- **Independent development**: Extensions can be built separately from Superset's codebase
-- **Version isolation**: Each extension can be developed with its own release cycle
-- **Shared dependencies**: Common libraries are shared, reducing memory usage and bundle size
-- **Type safety**: TypeScript types flow from the core package to extensions
-
-## Next Steps
-
-Now that you understand the architecture, explore:
-
-- **[Quick Start](./quick-start)** - Build your first extension
-- **[Contribution Types](./contribution-types)** - What kinds of extensions you can build
-- **[Development](./development)** - Project structure, APIs, and development workflow

docs/developer_portal/extensions/built-in-features.md

@@ -0,0 +1,36 @@
+---
+title: What This Means for Superset's Built-in Features
+sidebar_position: 13
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# What This Means for Superset's Built-in Features
+
+Transitioning to a well-defined, versioned API model has significant implications for Superset's built-in features. By exposing stable, public APIs for core functionality, we enable both extensions and internal modules to interact with the application in a consistent and predictable way. This approach brings several key benefits:
+
+- **Unified API Surface**: All important features of Superset will be accessible through documented, versioned APIs. This not only empowers extension authors but also ensures that built-in features use the same mechanisms, validating the APIs through real-world usage and making it easier to replace or enhance individual features over time.
+- **Dogfooding and Replaceability**: By building Superset's own features using the same APIs available to extensions, we ensure that these APIs are robust, flexible, and well-tested. This also means that any built-in feature can potentially be replaced or extended by a third-party extension, increasing modularity and adaptability.
+- **Versioned and Stable Contracts**: Public APIs will be versioned and follow semantic versioning, providing stability for both internal and external consumers. This stability is critical for long-term maintainability, but it also means that extra care must be taken to avoid breaking changes and to provide clear migration paths when changes are necessary.
+- **Improved Inter-Module Communication**: With clearly defined APIs and a command-based architecture, modules and extensions can communicate through explicit interfaces rather than relying on direct Redux store access or tightly coupled state management. This decouples modules, reduces the risk of unintended side effects, and makes the codebase easier to reason about and maintain.
+- **Facilitated Refactoring and Evolution**: As the application evolves, having a stable API layer allows for internal refactoring and optimization without breaking consumers. This makes it easier to modernize or optimize internal implementations while preserving compatibility.
+- **Clearer Documentation and Onboarding**: A public, versioned API surface makes it easier to document and onboard new contributors, both for core development and for extension authors.
+
+Overall, this shift represents a move toward a more modular, maintainable, and extensible architecture, where both built-in features and extensions are first-class citizens, and where the boundaries between core and community-driven innovation are minimized.

docs/developer_portal/extensions/contribution-types.md

@@ -1,130 +0,0 @@
----
-title: Contribution Types
-sidebar_position: 4
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Contribution Types
-
-To facilitate the development of extensions, we define a set of well-defined contribution types that extensions can implement. These contribution types serve as the building blocks for extensions, allowing them to interact with the host application and provide new functionality.
-
-## Frontend
-
-Frontend contribution types allow extensions to extend Superset's user interface with new views, commands, and menu items.
-
-### Views
-
-Extensions can add new views or panels to the host application, such as custom SQL Lab panels, dashboards, or other UI components. Each view is registered with a unique ID and can be activated or deactivated as needed. Contribution areas are uniquely identified (e.g., `sqllab.panels` for SQL Lab panels), enabling seamless integration into specific parts of the application.
-
-``` json
-"frontend": {
-  "contributions": {
-    "views": {
-      "sqllab.panels": [
-        {
-          "id": "my_extension.main",
-          "name": "My Panel Name"
-        }
-      ]
-    }
-  }
-}
-```
-
-### Commands
-
-Extensions can define custom commands that can be executed within the host application, such as context-aware actions or menu options. Each command can specify properties like a unique command identifier, an icon, a title, and a description. These commands can be invoked by users through menus, keyboard shortcuts, or other UI elements, enabling extensions to add rich, interactive functionality to Superset.
-
-``` json
-"frontend": {
-  "contributions": {
-    "commands": [
-      {
-        "command": "my_extension.copy_query",
-        "icon": "CopyOutlined",
-        "title": "Copy Query",
-        "description": "Copy the current query to clipboard"
-      }
-    ]
-  }
-}
-```
-
-### Menus
-
-Extensions can contribute new menu items or context menus to the host application, providing users with additional actions and options. Each menu item can specify properties such as the target view, the command to execute, its placement (primary, secondary, or context), and conditions for when it should be displayed. Menu contribution areas are uniquely identified (e.g., `sqllab.editor` for the SQL Lab editor), allowing extensions to seamlessly integrate their functionality into specific menus and workflows within Superset.
-
-``` json
-"frontend": {
-  "contributions": {
-    "menus": {
-      "sqllab.editor": {
-        "primary": [
-          {
-            "view": "builtin.editor",
-            "command": "my_extension.copy_query"
-          }
-        ],
-        "secondary": [
-          {
-            "view": "builtin.editor",
-            "command": "my_extension.prettify"
-          }
-        ],
-        "context": [
-          {
-            "view": "builtin.editor",
-            "command": "my_extension.clear"
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-## Backend
-
-Backend contribution types allow extensions to extend Superset's server-side capabilities with new API endpoints, MCP tools, and MCP prompts.
-
-### REST API Endpoints
-
-Extensions can register custom REST API endpoints under the `/api/v1/extensions/` namespace. This dedicated namespace prevents conflicts with built-in endpoints and provides a clear separation between core and extension functionality.
-
-``` json
-"backend": {
-  "entryPoints": ["my_extension.entrypoint"],
-  "files": ["backend/src/my_extension/**/*.py"]
-}
-```
-
-The entry point module registers the API with Superset:
-
-``` python
-from superset_core.api.rest_api import add_extension_api
-from .api import MyExtensionAPI
-
-add_extension_api(MyExtensionAPI)
-```
-
-### MCP Tools and Prompts
-
-Extensions can contribute Model Context Protocol (MCP) tools and prompts that AI agents can discover and use. See [MCP Integration](./mcp) for detailed documentation.

docs/developer_portal/extensions/deploying-extension.md

@@ -1,6 +1,6 @@
 ---
-title: Deployment
-sidebar_position: 6
+title: Deploying an Extension
+sidebar_position: 8
 ---
 
 <!--
@@ -22,7 +22,7 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Deployment
+# Deploying an Extension
 
 Once an extension has been developed, the deployment process involves packaging and uploading it to the host application.
 
@@ -33,17 +33,13 @@ Packaging is handled by the `superset-extensions bundle` command, which:
 3. Generates a `manifest.json` with build-time metadata, including the contents of `extension.json` and references to built assets.
 4. Packages everything into a `.supx` file (a zip archive with a specific structure required by Superset).
 
-To deploy an extension, place the `.supx` file in the extensions directory configured via `EXTENSIONS_PATH` in your `superset_config.py`:
+Uploading is accomplished through Superset's REST API at `/api/v1/extensions/import/`. The endpoint accepts the `.supx` file as form data and processes it by:
 
-``` python
-EXTENSIONS_PATH = "/path/to/extensions"
-```
+1. Extracting and validating the extension metadata and manifest.
+2. Storing extension assets in the metadata database for dynamic loading.
+3. Registering the extension in the metadata database, including its name, version, author, and capabilities.
+4. Automatically activating the extension, making it immediately available for use and management via the Superset UI or API.
 
-During application startup, Superset automatically discovers and loads all `.supx` files from this directory:
+This API-driven approach enables automated deployment workflows and simplifies extension management for administrators. Extensions can be uploaded through the Swagger UI, programmatically via scripts, or through the management interface:
 
-1. Scans the configured directory for `.supx` files.
-2. Validates each file is a properly formatted zip archive.
-3. Extracts and validates the extension manifest and metadata.
-4. Loads the extension, making it available for use.
-
-This file-based approach simplifies deployment in containerized environments and enables version control of extensions alongside infrastructure configuration.
+https://github.com/user-attachments/assets/98b16cdd-8ec5-4812-9d5e-9915badd8f0d

docs/developer_portal/extensions/development-mode.md

@@ -0,0 +1,48 @@
+---
+title: Development Mode
+sidebar_position: 10
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Development Mode
+
+Development mode accelerates extension development by letting developers see changes in Superset quickly, without the need for repeated packaging and uploading. To enable development mode, set the `LOCAL_EXTENSIONS` configuration in your `superset_config.py`:
+
+``` python
+LOCAL_EXTENSIONS = [
+    "/path/to/your/extension1",
+    "/path/to/your/extension2",
+]
+```
+
+This instructs Superset to load and serve extensions directly from disk, so you can iterate quickly. Running `superset-extensions dev` watches for file changes and rebuilds assets automatically, while the Webpack development server (started separately with `npm run dev-server`) serves updated files as soon as they're modified. This enables immediate feedback for React components, styles, and other frontend code. Changes to backend files are also detected automatically and immediately synced, ensuring that both frontend and backend updates are reflected in your development environment.
+
+Example output when running in development mode:
+
+```
+superset-extensions dev
+
+⚙️  Building frontend assets…
+✅ Frontend rebuilt
+✅ Backend files synced
+✅ Manifest updated
+👀 Watching for changes in: /dataset_references/frontend, /dataset_references/backend
+```

docs/developer_portal/extensions/development.md

@@ -1,239 +0,0 @@
----
-title: Development
-sidebar_position: 5
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Development
-
-This guide covers everything you need to know about developing extensions for Superset, from project structure to development workflow.
-
-## Project Structure
-
-The [apache-superset-extensions-cli](https://github.com/apache/superset/tree/master/superset-extensions-cli) package provides a command-line interface (CLI) that streamlines the extension development workflow. It offers the following commands:
-
-```
-superset-extensions init: Generates the initial folder structure and scaffolds a new extension project.
-
-superset-extensions build: Builds extension assets.
-
-superset-extensions bundle: Packages the extension into a .supx file.
-
-superset-extensions dev: Automatically rebuilds the extension as files change.
-```
-
-When creating a new extension with `superset-extensions init <extension-name>`, the CLI generates a standardized folder structure:
-
-```
-dataset_references/
-├── extension.json
-├── frontend/
-│   ├── src/
-│   ├── webpack.config.js
-│   ├── tsconfig.json
-│   └── package.json
-├── backend/
-│   ├── src/
-│        └── dataset_references/
-│   ├── tests/
-│   ├── pyproject.toml
-│   └── requirements.txt
-├── dist/
-│   ├── manifest.json
-│   ├── frontend
-│        └── dist/
-│             ├── remoteEntry.d7a9225d042e4ccb6354.js
-│             └── 900.038b20cdff6d49cfa8d9.js
-│   └── backend
-│        └── dataset_references/
-│             ├── __init__.py
-│             ├── api.py
-│             └── entrypoint.py
-├── dataset_references-1.0.0.supx
-└── README.md
-```
-
-The `extension.json` file serves as the declared metadata for the extension, containing the extension's name, version, author, description, and a list of capabilities. This file is essential for the host application to understand how to load and manage the extension.
-
-The `frontend` directory contains the source code for the frontend components of the extension, including React components, styles, and assets. The `webpack.config.js` file is used to configure Webpack for building the frontend code, while the `tsconfig.json` file defines the TypeScript configuration for the project. The `package.json` file specifies the dependencies and scripts for building and testing the frontend code.
-
-The `backend` directory contains the source code for the backend components of the extension, including Python modules, tests, and configuration files. The `pyproject.toml` file is used to define the Python package and its dependencies, while the `requirements.txt` file lists the required Python packages for the extension. The `src` folder contains the functional backend source files, `tests` directory contains unit tests for the backend code, ensuring that the extension behaves as expected and meets the defined requirements.
-
-The `dist` directory is built when running the `build` or `dev` command, and contains the files that will be included in the bundle. The `manifest.json` file contains critical metadata about the extension, including the majority of the contents of the `extension.json` file, but also other build-time information, like the name of the built Webpack Module Federation remote entry file. The files in the `dist` directory will be zipped into the final `.supx` file. Although this file is technically a zip archive, the `.supx` extension makes it clear that it is a Superset extension package and follows a specific file layout. This packaged file can be distributed and installed in Superset instances.
-
-The `README.md` file provides documentation and instructions for using the extension, including how to install, configure, and use its functionality.
-
-## Extension Metadata
-
-The `extension.json` file contains all metadata necessary for the host application to understand and manage the extension:
-
-```json
-{
-  "name": "dataset_references",
-  "version": "1.0.0",
-  "frontend": {
-    "contributions": {
-      "views": {
-        "sqllab.panels": [
-          {
-            "id": "dataset_references.main",
-            "name": "Dataset references"
-          }
-        ]
-      }
-    },
-    "moduleFederation": {
-      "exposes": ["./index"]
-    }
-  },
-  "backend": {
-    "entryPoints": ["dataset_references.entrypoint"],
-    "files": ["backend/src/dataset_references/**/*.py"]
-  }
-}
-```
-
-The `contributions` section declares how the extension extends Superset's functionality through views, commands, menus, and other contribution types. The `backend` section specifies entry points and files to include in the bundle.
-
-## Interacting with the Host
-
-Extensions interact with Superset through well-defined, versioned APIs provided by the `@apache-superset/core` (frontend) and `apache-superset-core` (backend) packages. These APIs are designed to be stable, discoverable, and consistent for both built-in and external extensions.
-
-**Note**: The `superset_core.api` module provides abstract classes that are replaced with concrete implementations via dependency injection when Superset initializes. This allows extensions to use the same interfaces as the host application.
-
-### Frontend APIs
-
-The frontend extension APIs (via `@apache-superset/core`) are organized into logical namespaces such as `authentication`, `commands`, `extensions`, `sqlLab`, and others. Each namespace groups related functionality, making it easy for extension authors to discover and use the APIs relevant to their needs. For example, the `sqlLab` namespace provides events and methods specific to SQL Lab, allowing extensions to react to user actions and interact with the SQL Lab environment:
-
-```typescript
-export const getCurrentTab: () => Tab | undefined;
-
-export const getDatabases: () => Database[];
-
-export const getTabs: () => Tab[];
-
-export const onDidChangeEditorContent: Event<string>;
-
-export const onDidClosePanel: Event<Panel>;
-
-export const onDidChangeActivePanel: Event<Panel>;
-
-export const onDidChangeTabTitle: Event<string>;
-
-export const onDidQueryRun: Event<Editor>;
-
-export const onDidQueryStop: Event<Editor>;
-```
-
-The following code demonstrates more examples of the existing frontend APIs:
-
-```typescript
-import { core, commands, sqlLab, authentication, Button } from '@apache-superset/core';
-import MyPanel from './MyPanel';
-
-export function activate(context) {
-  // Register a new panel (view) in SQL Lab and use shared UI components in your extension's React code
-  const panelDisposable = core.registerView('my_extension.panel', <MyPanel><Button/></MyPanel>);
-
-  // Register a custom command
-  const commandDisposable = commands.registerCommand('my_extension.copy_query', {
-    title: 'Copy Query',
-    execute: () => {
-      // Command logic here
-    },
-  });
-
-  // Listen for query run events in SQL Lab
-  const eventDisposable = sqlLab.onDidQueryRun(editor => {
-    // Handle query execution event
-  });
-
-  // Access a CSRF token for secure API requests
-  authentication.getCSRFToken().then(token => {
-    // Use token as needed
-  });
-
-  // Add all disposables for automatic cleanup on deactivation
-  context.subscriptions.push(panelDisposable, commandDisposable, eventDisposable);
-}
-```
-
-### Backend APIs
-
-Backend APIs (via `apache-superset-core`) follow a similar pattern, providing access to Superset's models, sessions, and query capabilities. Extensions can register REST API endpoints, access the metadata database, and interact with Superset's core functionality.
-
-Extension endpoints are registered under a dedicated `/extensions` namespace to avoid conflicting with built-in endpoints and also because they don't share the same version constraints. By grouping all extension endpoints under `/extensions`, Superset establishes a clear boundary between core and extension functionality, making it easier to manage, document, and secure both types of APIs.
-
-```python
-from superset_core.api.models import Database, get_session
-from superset_core.api.daos import DatabaseDAO
-from superset_core.api.rest_api import add_extension_api
-from .api import DatasetReferencesAPI
-
-# Register a new extension REST API
-add_extension_api(DatasetReferencesAPI)
-
-# Fetch Superset entities via the DAO to apply base filters that filter out entities
-# that the user doesn't have access to
-databases = DatabaseDAO.find_all()
-
-# ..or apply simple filters on top of base filters
-databases = DatabaseDAO.filter_by(uuid=database.uuid)
-if not databases:
-    raise Exception("Database not found")
-
-return databases[0]
-
-# Perform complex queries using SQLAlchemy Query, also filtering out
-# inaccessible entities
-session = get_session()
-databases_query = session.query(Database).filter(
-    Database.database_name.ilike("%abc%")
-)
-return DatabaseDAO.query(databases_query)
-```
-
-In the future, we plan to expand the backend APIs to support configuring security models, database engines, SQL Alchemy dialects, etc.
-
-## Development Mode
-
-Development mode accelerates extension development by letting developers see changes in Superset quickly, without the need for repeated packaging and uploading. To enable development mode, set the `LOCAL_EXTENSIONS` configuration in your `superset_config.py`:
-
-```python
-LOCAL_EXTENSIONS = [
-    "/path/to/your/extension1",
-    "/path/to/your/extension2",
-]
-```
-
-This instructs Superset to load and serve extensions directly from disk, so you can iterate quickly. Running `superset-extensions dev` watches for file changes and rebuilds assets automatically, while the Webpack development server (started separately with `npm run dev-server`) serves updated files as soon as they're modified. This enables immediate feedback for React components, styles, and other frontend code. Changes to backend files are also detected automatically and immediately synced, ensuring that both frontend and backend updates are reflected in your development environment.
-
-Example output when running in development mode:
-
-```
-superset-extensions dev
-
-⚙️  Building frontend assets…
-✅ Frontend rebuilt
-✅ Backend files synced
-✅ Manifest updated
-👀 Watching for changes in: /dataset_references/frontend, /dataset_references/backend
-```

docs/developer_portal/extensions/dynamic-module-loading.md

@@ -0,0 +1,84 @@
+---
+title: Dynamic Module Loading
+sidebar_position: 7
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Dynamic Module Loading
+
+The extension architecture leverages Webpack's Module Federation to enable dynamic loading of frontend assets at runtime. This sophisticated mechanism involves several key concepts:
+
+**Module Federation** allows extensions to be built and deployed independently while sharing dependencies with the host application. Extensions expose their entry points through the federation configuration:
+
+``` typescript
+new ModuleFederationPlugin({
+  name: 'my_extension',
+  filename: 'remoteEntry.[contenthash].js',
+  exposes: {
+    './index': './src/index.tsx',
+  },
+  externalsType: 'window',
+  externals: {
+    '@apache-superset/core': 'superset',
+  },
+  shared: {
+    react: { singleton: true },
+    'react-dom': { singleton: true },
+    'antd-v5': { singleton: true }
+  }
+})
+```
+
+`externals` and `externalsType` ensure that extensions use the host's implementation of shared packages rather than bundling their own copies.
+
+`shared` dependencies prevent duplication of common libraries like React and Ant Design avoiding version conflicts and reducing bundle size.
+
+This configuration tells Webpack that when the extension imports from `@apache-superset/core`, it should resolve to `window.superset` at runtime, where the host application provides the actual implementation. The following diagram illustrates how this works in practice:
+
+<img width="913" height="558" alt="Image" src="https://github.com/user-attachments/assets/e5e4d2ae-e8b5-4d17-a2a1-3667c65f25ca" />
+
+During extension registration, the host application fetches the remote entry file and dynamically loads the extension's modules without requiring a rebuild or restart of Superset.
+
+On the host application side, the `@apache-superset/core` package will be mapped to the corresponding implementations during bootstrap in the `setupExtensionsAPI` function.
+
+``` typescript
+import * as supersetCore from '@apache-superset/core';
+import {
+  authentication,
+  core,
+  commands,
+  environment,
+  extensions,
+  sqlLab,
+} from 'src/extensions';
+
+export default function setupExtensionsAPI() {
+  window.superset = {
+    ...supersetCore,
+    authentication,
+    core,
+    commands,
+    environment,
+    extensions,
+    sqlLab,
+  };
+}
+```

docs/developer_portal/extensions/extension-metadata.md

@@ -0,0 +1,55 @@
+---
+title: Extension Metadata
+sidebar_position: 4
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Extension Metadata
+
+The `extension.json` file contains all metadata necessary for the host application to understand and manage the extension:
+
+``` json
+{
+  "name": "dataset_references",
+  "version": "1.0.0",
+  "frontend": {
+    "contributions": {
+      "views": {
+        "sqllab.panels": [
+          {
+            "id": "dataset_references.main",
+            "name": "Dataset references"
+          }
+        ]
+      }
+    },
+    "moduleFederation": {
+      "exposes": ["./index"]
+    }
+  },
+  "backend": {
+    "entryPoints": ["dataset_references.entrypoint"],
+    "files": ["backend/src/dataset_references/**/*.py"]
+  },
+}
+```
+
+The `contributions` section declares how the extension extends Superset's functionality through views, commands, menus, and other contribution types. The `backend` section specifies entry points and files to include in the bundle.

docs/developer_portal/extensions/extension-points/sqllab.md

@@ -1,209 +0,0 @@
----
-title: SQL Lab
-sidebar_position: 1
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# SQL Lab Extension Points
-
-SQL Lab provides 5 extension points where extensions can contribute custom UI components. Each area serves a specific purpose and can be customized to add new functionality.
-
-## Layout Overview
-
-```
-┌──────────┬─────────────────────────────────────────┬─────────────┐
-│          │                                         │             │
-│          │                                         │             │
-│          │                Editor                   │             │
-│          │                                         │             │
-│   Left   │                                         │    Right    │
-│  Sidebar ├─────────────────────────────────────────┤   Sidebar   │
-│          │                                         │             │
-│          │                Panels                   │             │
-│          │                                         │             │
-│          │                                         │             │
-│          │                                         │             │
-├──────────┴─────────────────────────────────────────┴─────────────┤
-│                          Status Bar                              │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-| Extension Point   | ID                    | Description                                                |
-| ----------------- | --------------------- | ---------------------------------------------------------- |
-| **Left Sidebar**  | `sqllab.leftSidebar`  | Navigation and browsing (database explorer, saved queries) |
-| **Editor**        | `sqllab.editor`       | SQL query editor workspace                                 |
-| **Right Sidebar** | `sqllab.rightSidebar` | Contextual tools (AI assistants, query analysis)           |
-| **Panels**        | `sqllab.panels`       | Results and related views (visualizations, data profiling) |
-| **Status Bar**    | `sqllab.statusBar`    | Connection status and query metrics                        |
-
-## Area Customizations
-
-Each extension point area supports three types of action customizations:
-
-```
-┌───────────────────────────────────────────────────────────────┐
-│  Area Title                         [Button] [Button]   [•••] │
-├───────────────────────────────────────────────────────────────┤
-│                                                               │
-│                                                               │
-│                          Area Content                         │
-│                                                               │
-│                  (right-click for context menu)               │
-│                                                               │
-│                                                               │
-└───────────────────────────────────────────────────────────────┘
-```
-
-| Action Type           | Location          | Use Case                                              |
-| --------------------- | ----------------- | ----------------------------------------------------- |
-| **Primary Actions**   | Top-right buttons | Frequently used actions (e.g., run, refresh, add new) |
-| **Secondary Actions** | 3-dot menu (•••)  | Less common actions (e.g., export, settings)          |
-| **Context Actions**   | Right-click menu  | Context-sensitive actions on content                  |
-
-## Examples
-
-### Adding a Panel
-
-This example adds a "Data Profiler" panel to SQL Lab:
-
-```json
-{
-  "name": "data_profiler",
-  "version": "1.0.0",
-  "frontend": {
-    "contributions": {
-      "views": {
-        "sqllab.panels": [
-          {
-            "id": "data_profiler.main",
-            "name": "Data Profiler"
-          }
-        ]
-      }
-    }
-  }
-}
-```
-
-```typescript
-import { core } from '@apache-superset/core';
-import DataProfilerPanel from './DataProfilerPanel';
-
-export function activate(context) {
-  // Register the panel view with the ID declared in extension.json
-  const disposable = core.registerView('data_profiler.main', <DataProfilerPanel />);
-  context.subscriptions.push(disposable);
-}
-```
-
-### Adding Actions to the Editor
-
-This example adds primary, secondary, and context actions to the editor:
-
-```json
-{
-  "name": "query_tools",
-  "version": "1.0.0",
-  "frontend": {
-    "contributions": {
-      "commands": [
-        {
-          "command": "query_tools.format",
-          "title": "Format Query",
-          "icon": "FormatPainterOutlined"
-        },
-        {
-          "command": "query_tools.explain",
-          "title": "Explain Query"
-        },
-        {
-          "command": "query_tools.copy_as_cte",
-          "title": "Copy as CTE"
-        }
-      ],
-      "menus": {
-        "sqllab.editor": {
-          "primary": [
-            {
-              "view": "builtin.editor",
-              "command": "query_tools.format"
-            }
-          ],
-          "secondary": [
-            {
-              "view": "builtin.editor",
-              "command": "query_tools.explain"
-            }
-          ],
-          "context": [
-            {
-              "view": "builtin.editor",
-              "command": "query_tools.copy_as_cte"
-            }
-          ]
-        }
-      }
-    }
-  }
-}
-```
-
-```typescript
-import { commands, sqlLab } from '@apache-superset/core';
-
-export function activate(context) {
-  // Register the commands declared in extension.json
-  const formatCommand = commands.registerCommand('query_tools.format', {
-    execute: () => {
-      const tab = sqlLab.getCurrentTab();
-      if (tab?.editor) {
-        // Format the SQL query
-      }
-    },
-  });
-
-  const explainCommand = commands.registerCommand('query_tools.explain', {
-    execute: () => {
-      const tab = sqlLab.getCurrentTab();
-      if (tab?.editor) {
-        // Show query explanation
-      }
-    },
-  });
-
-  const copyAsCteCommand = commands.registerCommand('query_tools.copy_as_cte', {
-    execute: () => {
-      const tab = sqlLab.getCurrentTab();
-      if (tab?.editor) {
-        // Copy selected text as CTE
-      }
-    },
-  });
-
-  context.subscriptions.push(formatCommand, explainCommand, copyAsCteCommand);
-}
-```
-
-## Next Steps
-
-- **[Contribution Types](../contribution-types)** - Learn about other contribution types (commands, menus)
-- **[Development](../development)** - Set up your development environment
-- **[Quick Start](../quick-start)** - Build a complete extension

docs/developer_portal/extensions/extension-project-structure.md

@@ -0,0 +1,78 @@
+---
+title: Extension Project Structure
+sidebar_position: 3
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Extension Project Structure
+
+The `apache-superset-extensions-cli` package provides a command-line interface (CLI) that streamlines the extension development workflow. It offers the following commands:
+
+```
+superset-extensions init: Generates the initial folder structure and scaffolds a new extension project.
+
+superset-extensions build: Builds extension assets.
+
+superset-extensions bundle: Packages the extension into a .supx file.
+
+superset-extensions dev: Automatically rebuilds the extension as files change.
+```
+
+When creating a new extension with `superset-extensions init <extension-name>`, the CLI generates a standardized folder structure:
+
+```
+dataset_references/
+├── extension.json
+├── frontend/
+│   ├── src/
+│   ├── webpack.config.js
+│   ├── tsconfig.json
+│   └── package.json
+├── backend/
+│   ├── src/
+│        └── dataset_references/
+│   ├── tests/
+│   ├── pyproject.toml
+│   └── requirements.txt
+├── dist/
+│   ├── manifest.json
+│   ├── frontend
+│        └── dist/
+│             ├── remoteEntry.d7a9225d042e4ccb6354.js
+│             └── 900.038b20cdff6d49cfa8d9.js
+│   └── backend
+│        └── dataset_references/
+│             ├── __init__.py
+│             ├── api.py
+│             └── entrypoint.py
+├── dataset_references-1.0.0.supx
+└── README.md
+```
+
+The `extension.json` file serves as the declared metadata for the extension, containing the extension's name, version, author, description, and a list of capabilities. This file is essential for the host application to understand how to load and manage the extension.
+
+The `frontend` directory contains the source code for the frontend components of the extension, including React components, styles, and assets. The `webpack.config.js` file is used to configure Webpack for building the frontend code, while the `tsconfig.json` file defines the TypeScript configuration for the project. The `package.json` file specifies the dependencies and scripts for building and testing the frontend code.
+
+The `backend` directory contains the source code for the backend components of the extension, including Python modules, tests, and configuration files. The `pyproject.toml` file is used to define the Python package and its dependencies, while the r`equirements.txt` file lists the required Python packages for the extension. The `src` folder contains the functional backend source files, `tests` directory contains unit tests for the backend code, ensuring that the extension behaves as expected and meets the defined requirements.
+
+The `dist` directory is built when running the `build` or `dev` command, and contains the files that will be included in the bundle. The `manifest.json` file contains critical metadata about the extension, including the majority of the contents of the `extension.json` file, but also other build-time information, like the name of the built Webpack Module Federation remote entry file. The files in the `dist` directory will be zipped into the final `.supx` file. Although this file is technically a zip archive, the `.supx` extension makes it clear that it is a Superset extension package and follows a specific file layout. This packaged file can be distributed and installed in Superset instances.
+
+The `README.md` file provides documentation and instructions for using the extension, including how to install, configure, and use its functionality.

docs/developer_portal/extensions/frontend-contribution-types.md

@@ -0,0 +1,90 @@
+---
+title: Frontend Contribution Types
+sidebar_position: 5
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Frontend Contribution Types
+
+To facilitate the development of extensions, we will define a set of well-defined contribution types that extensions can implement. These contribution types will serve as the building blocks for extensions, allowing them to interact with the host application and provide new functionality. The initial set of contribution types will include:
+
+## Views
+
+Extensions can add new views or panels to the host application, such as custom SQL Lab panels, dashboards, or other UI components. Each view is registered with a unique ID and can be activated or deactivated as needed. Contribution areas are uniquely identified (e.g., `sqllab.panels` for SQL Lab panels), enabling seamless integration into specific parts of the application.
+
+``` json
+"views": {
+  "sqllab.panels": [
+    {
+      "id": "dataset_references.main",
+      "name": "Table references"
+    }
+  ]
+},
+```
+
+## Commands
+
+Extensions can define custom commands that can be executed within the host application, such as context-aware actions or menu options. Each command can specify properties like a unique command identifier, an icon, a title, and a description. These commands can be invoked by users through menus, keyboard shortcuts, or other UI elements, enabling extensions to add rich, interactive functionality to Superset.
+
+``` json
+"commands": [
+  {
+    "command": "extension1.copy_query",
+    "icon": "CopyOutlined",
+    "title": "Copy Query",
+    "description": "Copy the current query to clipboard"
+  },
+]
+```
+
+## Menus
+
+Extensions can contribute new menu items or context menus to the host application, providing users with additional actions and options. Each menu item can specify properties such as the target view, the command to execute, its placement (primary, secondary, or context), and conditions for when it should be displayed. Menu contribution areas are uniquely identified (e.g., `sqllab.editor` for the SQL Lab editor), allowing extensions to seamlessly integrate their functionality into specific menus and workflows within Superset.
+
+``` json
+"menus": {
+  "sqllab.editor": {
+    "primary": [
+      {
+        "view": "builtin.editor",
+        "command": "extension1.copy_query"
+      }
+    ],
+    "secondary": [
+      {
+        "view": "builtin.editor",
+        "command": "extension1.prettify"
+      }
+    ],
+    "context": [
+      {
+        "view": "builtin.editor",
+        "command": "extension1.clear"
+      },
+      {
+        "view": "builtin.editor",
+     "command": "extension1.refresh"
+      }
+    ]
+  },
+}
+```

docs/developer_portal/extensions/high-level-architecture.md

@@ -0,0 +1,41 @@
+---
+title: High-level Architecture
+sidebar_position: 2
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# High-level Architecture
+
+It is important to note that this SIP is not intended to address every aspect of the architecture in a single document. Rather, it should be seen as a chapter in an ongoing book: it establishes foundational concepts and direction, while recognizing that many important topics remain to be explored. Many topics not covered here are expected to be addressed in subsequent SIPs as the architecture and community needs evolve.
+
+The following diagram illustrates the overall architecture, emphasizing the relationships between the host application, extensions, and the supporting packages that will be developed to enable this ecosystem.
+
+<img width="955" height="586" alt="Image" src="https://github.com/user-attachments/assets/cc2a41df-55a4-48c8-b056-35f7a1e567c6" />
+
+On the frontend side, as a result of discussions in [[SIP-169] Proposal for Extracting and Publishing Superset Core UI Components](https://github.com/apache/superset/issues/33441), the `@apache-superset/core` package will be created to provide all the essential building blocks for both the host application and extensions, including shared UI components, utility functions, APIs, and type definitions. By centralizing these resources, extensions and built-in features can use the same APIs and components, ensuring consistency, type safety, and a seamless user experience across the Superset ecosystem. This package will be versioned to support safe evolution of the platform while maintaining compatibility for both internal and external features.
+
+On the backend side, the `apache-superset-core` package will expose key classes and APIs needed by extensions that provide backend functionality such as extending Superset's API, providing database connectors, or customizing the security manager. It will contain dependencies on critical libraries like FAB, SQLAlchemy, etc and like `@apache-superset/core`, it will be versioned to ensure compatibility and stability.
+
+The `apache-superset-extensions-cli` package will provide a comprehensive set of CLI commands for extension development, including tools for code generation, building, and packaging extensions. These commands streamline the development workflow, making it easier for developers to scaffold new projects, build and bundle their code, and distribute extensions efficiently. By standardizing these processes, the CLI helps ensure that extensions are built in a consistent manner, remain compatible with evolving versions of Superset, and adhere to best practices across the ecosystem.
+
+Extension projects might have references to all packages, depending on their specific needs. For example, an extension that provides a custom SQL editor might depend on the `apache-superset-core` package for backend functionality, while also using the `@apache-superset/core` package for UI components and type definitions. This modular approach allows extension authors to choose the dependencies that best suit their needs, while also promoting consistency and reusability across the ecosystem.
+
+The host application (Superset) will depend on core packages and is responsible for providing the implementation of the APIs defined in them. It will expose a new endpoint (`/api/v1/extensions`) for extension registration and management, and a dedicated UI for managing extensions. Registered extensions will be stored in the metadata database in a table called `extensions`, which will contain information such as the extension's name, version, author, contributed features, exposed modules, relevant metadata and the built frontend and/or backend code.

docs/developer_portal/extensions/interacting-with-host.md

@@ -0,0 +1,120 @@
+---
+title: Interacting with the Host
+sidebar_position: 6
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Interacting with the Host
+
+Extensions interact with Superset through well-defined, versioned APIs provided by the `@apache-superset/core` (frontend) and `apache-superset-core` (backend) packages. These APIs are designed to be stable, discoverable, and consistent for both built-in and external extensions.
+
+**Frontend APIs** (via `@apache-superset/core)`:
+
+The frontend extension APIs in Superset are organized into logical namespaces such as `authentication`, `commands`, `extensions`, `sqlLab`, and others. Each namespace groups related functionality, making it easy for extension authors to discover and use the APIs relevant to their needs. For example, the `sqlLab` namespace provides events and methods specific to SQL Lab, allowing extensions to react to user actions and interact with the SQL Lab environment:
+
+``` typescript
+export const getCurrentTab: () => Tab | undefined;
+
+export const getDatabases: () => Database[];
+
+export const getTabs: () => Tab[];
+
+export const onDidChangeEditorContent: Event<string>;
+
+export const onDidClosePanel: Event<Panel>;
+
+export const onDidChangeActivePanel: Event<Panel>;
+
+export const onDidChangeTabTitle: Event<string>;
+
+export const onDidQueryRun: Event<Editor>;
+
+export const onDidQueryStop: Event<Editor>;
+```
+
+The following code demonstrates more examples of the existing frontend APIs:
+
+``` typescript
+import { core, commands, sqlLab, authentication, Button } from '@apache-superset/core';
+import MyPanel from './MyPanel';
+
+export function activate(context) {
+  // Register a new panel (view) in SQL Lab and use shared UI components in your extension's React code
+  const panelDisposable = core.registerView('my_extension.panel', <MyPanel><Button/></MyPanel>);
+
+  // Register a custom command
+  const commandDisposable = commands.registerCommand('my_extension.copy_query', {
+    title: 'Copy Query',
+    execute: () => {
+      // Command logic here
+    },
+  });
+
+  // Listen for query run events in SQL Lab
+  const eventDisposable = sqlLab.onDidQueryRun(editor => {
+    // Handle query execution event
+  });
+
+  // Access a CSRF token for secure API requests
+  authentication.getCSRFToken().then(token => {
+    // Use token as needed
+  });
+
+  // Add all disposables for automatic cleanup on deactivation
+  context.subscriptions.push(panelDisposable, commandDisposable, eventDisposable);
+}
+```
+
+**Backend APIs** (via `apache-superset-core`):
+
+Backend APIs follow a similar pattern, providing access to Superset's models, sessions, and query capabilities. Extensions can register REST API endpoints, access the metadata database, and interact with Superset's core functionality.
+
+Extension endpoints are registered under a dedicated `/extensions` namespace to avoid conflicting with built-in endpoints and also because they don't share the same version constraints. By grouping all extension endpoints under `/extensions`, Superset establishes a clear boundary between core and extension functionality, making it easier to manage, document, and secure both types of APIs.
+
+``` python
+from superset_core.api import rest_api, models, query
+from .api import DatasetReferencesAPI
+
+# Register a new extension REST API
+rest_api.add_extension_api(DatasetReferencesAPI)
+
+# Access Superset models with simple queries that filter out entities that
+# the user doesn't have access to
+databases = models.get_databases(id=database_id)
+if not databases:
+    return self.response_404()
+
+database = databases[0]
+
+# Perform complex queries using SQLAlchemy BaseQuery, also filtering
+# out inaccessible entities
+session = models.get_session()
+db_model = models.get_database_model())
+database_query = session.query(db_model.database_name.ilike("%abc%")
+databases_containing_abc = models.get_databases(query)
+
+# Bypass security model for highly custom use cases
+session = models.get_session()
+db_model = models.get_database_model())
+all_databases_containg_abc = session.query(db_model.database_name.ilike("%abc%").all()
+```
+
+In the future, we plan to expand the backend APIs to support configuring security models, database engines, SQL Alchemy dialects, etc.

docs/developer_portal/extensions/lifecycle-management.md

@@ -0,0 +1,41 @@
+---
+title: Lifecycle and Management
+sidebar_position: 9
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Lifecycle and Management
+
+Superset will manage the full lifecycle of extensions, including activation, deactivation, and cleanup. The lifecycle is designed to ensure that extensions can safely register resources and reliably clean them up when no longer needed.
+
+## Frontend lifecycle
+
+- When an extension is activated, its `activate(context)` function is called. The extension should register all event listeners, commands, views, and other contributions using the provided context, and add any disposables to `context.disposables`.
+- When the extension is deactivated (e.g., disabled or uninstalled), Superset automatically calls `dispose()` on all items in `context.disposables`, ensuring that event listeners, commands, and UI contributions are removed and memory leaks are avoided.
+
+## Backend lifecycle
+
+- Backend entry points, which can add REST API endpoints or execute arbitrary backend code, are eagerly evaluated during startup. Other backend code is lazily loaded when needed, ensuring minimal startup latency.
+- In the future, we plan to leverage mechanisms like Redis pub/sub (already an optional dependency of Superset) to dynamically manage the lifecycle of extensions' backend functionality. This will ensure that all running instances of the Superset backend have the same available extensions without requiring a restart. This will be addressed in a follow-up SIP.
+
+The proof-of-concept (POC) code for this SIP already implements a management module where administrators can upload, delete, enable/disable, and inspect the manifest for installed extensions via the Superset UI, making extension operations straightforward. These operations are currently supported dynamically for frontend extensions. For backend extensions, dynamic upload, deletion, and enable/disable are planned for a future iteration; at present, changes to backend extensions (such as uploading, deleting, or enabling/disabling) still require a server restart.
+
+https://github.com/user-attachments/assets/4eb7064b-3290-4e4c-b88b-52d8d1c11245

docs/developer_portal/extensions/mcp.md

@@ -1,459 +0,0 @@
----
-title: MCP Integration
-hide_title: true
-sidebar_position: 7
-version: 1
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# MCP Integration
-
-Model Context Protocol (MCP) integration allows extensions to register custom AI agent capabilities that integrate seamlessly with Superset's MCP service. Extensions can provide both **tools** (executable functions) and **prompts** (interactive guidance) that AI agents can discover and use.
-
-## What is MCP?
-
-MCP enables extensions to extend Superset's AI capabilities in two ways:
-
-### MCP Tools
-Tools are Python functions that AI agents can call to perform specific tasks. They provide executable functionality that extends Superset's capabilities.
-
-**Examples of MCP tools:**
-- Data processing and transformation functions
-- Custom analytics calculations
-- Integration with external APIs
-- Specialized report generation
-- Business-specific operations
-
-### MCP Prompts
-Prompts provide interactive guidance and context to AI agents. They help agents understand how to better assist users with specific workflows or domain knowledge.
-
-**Examples of MCP prompts:**
-- Step-by-step workflow guidance
-- Domain-specific context and knowledge
-- Interactive troubleshooting assistance
-- Template generation helpers
-- Best practices recommendations
-
-## Getting Started
-
-## MCP Tools
-
-### Basic Tool Registration
-
-The simplest way to create an MCP tool is using the `@tool` decorator:
-
-```python
-from superset_core.mcp import tool
-
-@tool
-def hello_world() -> dict:
-    """A simple greeting tool."""
-    return {"message": "Hello from my extension!"}
-```
-
-This creates a tool that AI agents can call by name. The tool name defaults to the function name.
-
-### Decorator Parameters
-
-The `@tool` decorator accepts several optional parameters:
-
-**Parameter details:**
-- **`name`**: Tool identifier (AI agents use this to call your tool)
-- **`description`**: Explains what the tool does (helps AI agents decide when to use it)
-- **`tags`**: Categories for organization and discovery
-- **`protect`**: Whether the tool requires user authentication (defaults to `True`)
-
-### Naming Your Tools
-
-For extensions, include your extension ID in tool names to avoid conflicts:
-
-## Complete Example
-
-Here's a more comprehensive example showing best practices:
-
-```python
-# backend/mcp_tools.py
-import random
-from datetime import datetime, timezone
-from pydantic import BaseModel, Field
-from superset_core.mcp import tool
-
-class RandomNumberRequest(BaseModel):
-    """Request schema for random number generation."""
-
-    min_value: int = Field(
-        description="Minimum value (inclusive) for random number generation",
-        ge=-2147483648,
-        le=2147483647
-    )
-    max_value: int = Field(
-        description="Maximum value (inclusive) for random number generation",
-        ge=-2147483648,
-        le=2147483647
-    )
-
-@tool(
-    name="example_extension.random_number",
-    tags=["extension", "utility", "random", "generator"]
-)
-def random_number_generator(request: RandomNumberRequest) -> dict:
-    """
-    Generate a random integer between specified bounds.
-
-    This tool validates input ranges and provides detailed error messages
-    for invalid requests.
-    """
-
-    # Validate business logic (Pydantic handles type/range validation)
-    if request.min_value > request.max_value:
-        return {
-            "status": "error",
-            "error": f"min_value ({request.min_value}) cannot be greater than max_value ({request.max_value})",
-            "timestamp": datetime.now(timezone.utc).isoformat()
-        }
-
-    # Generate random number
-    result = random.randint(request.min_value, request.max_value)
-
-    return {
-        "status": "success",
-        "random_number": result,
-        "min_value": request.min_value,
-        "max_value": request.max_value,
-        "range_size": request.max_value - request.min_value + 1,
-        "timestamp": datetime.now(timezone.utc).isoformat()
-    }
-```
-
-## Best Practices
-
-### Response Format
-
-Use consistent response structures:
-
-```python
-# Success response
-{
-    "status": "success",
-    "result": "your_data_here",
-    "timestamp": "2024-01-01T00:00:00Z"
-}
-
-# Error response
-{
-    "status": "error",
-    "error": "Clear error message",
-    "timestamp": "2024-01-01T00:00:00Z"
-}
-```
-
-### Documentation
-
-Write clear descriptions and docstrings:
-
-```python
-@tool(
-    name="my_extension.process_data",
-    description="Process customer data and generate insights. Requires valid customer ID and date range.",
-    tags=["analytics", "customer", "reporting"]
-)
-def process_data(customer_id: int, start_date: str, end_date: str) -> dict:
-    """
-    Process customer data for the specified date range.
-
-    This tool analyzes customer behavior patterns and generates
-    actionable insights for business decision-making.
-
-    Args:
-        customer_id: Unique customer identifier
-        start_date: Analysis start date (YYYY-MM-DD format)
-        end_date: Analysis end date (YYYY-MM-DD format)
-
-    Returns:
-        Dictionary containing analysis results and recommendations
-    """
-    # Implementation here
-    pass
-```
-
-### Tool Naming
-
-- **Extension tools**: Use prefixed names like `my_extension.tool_name`
-- **Descriptive names**: `calculate_tax_amount` vs `calculate`
-- **Consistent naming**: Follow patterns within your extension
-
-## How AI Agents Use Your Tools
-
-Once registered, AI agents can discover and use your tools automatically:
-
-```
-User: "Generate a random number between 1 and 100"
-Agent: I'll use the random number generator tool.
-→ Calls: example_extension.random_number(min_value=1, max_value=100)
-← Returns: {"status": "success", "random_number": 42, ...}
-Agent: I generated the number 42 for you.
-```
-
-The AI agent sees your tool's:
-- **Name**: How to call it
-- **Description**: What it does and when to use it
-- **Parameters**: What inputs it expects (from Pydantic schema)
-- **Tags**: Categories for discovery
-
-## Troubleshooting
-
-### Tool Not Available to AI Agents
-
-1. **Check extension registration**: Verify your tool module is listed in extension entrypoints
-2. **Verify decorator**: Ensure `@tool` is correctly applied
-3. **Extension loading**: Confirm your extension is installed and enabled
-
-### Input Validation Errors
-
-1. **Pydantic models**: Ensure field types match expected inputs
-2. **Field constraints**: Check min/max values and string lengths are reasonable
-3. **Required fields**: Verify which parameters are required vs optional
-
-### Runtime Issues
-
-1. **Error handling**: Add try/catch blocks with clear error messages
-2. **Response format**: Use consistent status/error/timestamp structure
-3. **Testing**: Test your tools with various input scenarios
-
-### Development Tips
-
-1. **Start simple**: Begin with basic tools, add complexity gradually
-2. **Test locally**: Use MCP clients (like Claude Desktop) to test your tools
-3. **Clear descriptions**: Write tool descriptions as if explaining to a new user
-4. **Meaningful tags**: Use tags that help categorize and discover tools
-5. **Error messages**: Provide specific, actionable error messages
-
-## MCP Prompts
-
-### Basic Prompt Registration
-
-Create interactive prompts using the `@prompt` decorator:
-
-```python
-from superset_core.mcp import prompt
-from fastmcp import Context
-
-@prompt("my_extension.workflow_guide")
-async def workflow_guide(ctx: Context) -> str:
-    """Interactive guide for data analysis workflows."""
-    return """
-    # Data Analysis Workflow Guide
-
-    Here's a step-by-step approach to effective data analysis in Superset:
-
-    ## 1. Data Discovery
-    - Start by exploring your datasets using the dataset browser
-    - Check data quality and identify key metrics
-    - Look for patterns and relationships in your data
-
-    ## 2. Chart Creation
-    - Choose appropriate visualizations for your data types
-    - Apply filters to focus on relevant subsets
-    - Configure proper aggregations and groupings
-
-    ## 3. Dashboard Assembly
-    - Combine related charts into coherent dashboards
-    - Use filters and parameters for interactivity
-    - Add markdown components for context and explanations
-
-    Would you like guidance on any specific step?
-    """
-```
-
-### Advanced Prompt Examples
-
-#### Domain-Specific Context
-
-```python
-@prompt(
-    "sales_extension.sales_analysis_guide",
-    title="Sales Analysis Guide",
-    description="Specialized guidance for sales data analysis workflows"
-)
-async def sales_analysis_guide(ctx: Context) -> str:
-    """Provides sales-specific analysis guidance and best practices."""
-    return """
-    # Sales Data Analysis Best Practices
-
-    ## Key Metrics to Track
-    - **Revenue Growth**: Month-over-month and year-over-year trends
-    - **Conversion Rates**: Lead-to-opportunity-to-close ratios
-    - **Customer Lifetime Value**: Total value per customer segment
-    - **Sales Cycle Length**: Time from lead to close by product/region
-
-    ## Recommended Chart Types
-    - **Time Series**: Revenue trends, seasonal patterns
-    - **Funnel Charts**: Conversion analysis across sales stages
-    - **Geographic Maps**: Regional performance comparison
-    - **Cohort Analysis**: Customer retention and growth patterns
-
-    ## Common Pitfalls to Avoid
-    - Don't mix different time granularities without proper context
-    - Always normalize for business days when comparing periods
-    - Consider external factors (holidays, market events) in analysis
-    - Segment by relevant dimensions (product, region, channel)
-
-    ## Next Steps
-    1. Identify your primary sales KPIs
-    2. Create baseline trend charts for each metric
-    3. Build comparative views across segments
-    4. Set up automated alerts for significant changes
-    """
-```
-
-#### Interactive Troubleshooting
-
-```python
-@prompt("support_extension.troubleshoot_charts")
-async def troubleshoot_charts(ctx: Context) -> str:
-    """Interactive troubleshooting assistant for chart issues."""
-    return """
-    # Chart Troubleshooting Assistant
-
-    Let's diagnose your chart issue step by step:
-
-    ## Common Issues and Solutions
-
-    ### 🚫 No Data Showing
-    **Possible causes:**
-    - Filters are too restrictive
-    - Date range doesn't match your data
-    - Database connection issues
-    - Missing permissions
-
-    **Check:** Try removing all filters and expanding the date range first.
-
-    ### 📊 Unexpected Aggregation Results
-    **Possible causes:**
-    - Incorrect grouping dimensions
-    - Wrong aggregation function (SUM vs COUNT vs AVG)
-    - Data quality issues (duplicates, nulls)
-    - Time zone mismatches
-
-    **Check:** Verify your GROUP BY columns and aggregation logic.
-
-    ### 🐌 Slow Performance
-    **Possible causes:**
-    - Large dataset without proper indexing
-    - Complex joins or calculations
-    - Missing query optimizations
-    - Resource constraints
-
-    **Check:** Simplify the query and add appropriate filters first.
-
-    ## Debug Steps
-    1. **Start Simple**: Create a basic count query first
-    2. **Add Gradually**: Introduce complexity step by step
-    3. **Check SQL**: Review the generated SQL for issues
-    4. **Test Data**: Verify with a small sample first
-
-    What specific issue are you experiencing?
-    """
-```
-
-### Prompt Best Practices
-
-#### Content Structure
-- **Use clear headings** and sections for easy navigation
-- **Provide actionable steps** rather than just theory
-- **Include examples** relevant to the user's domain
-- **Offer next steps** to continue the workflow
-
-#### Interactive Design
-- **Ask questions** to engage the user
-- **Provide options** for different scenarios
-- **Reference specific Superset features** by name
-- **Link to related tools** when appropriate
-
-#### Context Awareness
-```python
-@prompt("analytics_extension.context_aware_guide")
-async def context_aware_guide(ctx: Context) -> str:
-    """Provides guidance based on current user context."""
-    # Access user information if available
-    user_info = getattr(ctx, 'user', None)
-
-    guidance = """# Personalized Analytics Guide\n\n"""
-
-    if user_info:
-        guidance += f"Welcome back! Here's guidance tailored for your role:\n\n"
-
-    guidance += """
-    ## Getting Started
-    Based on your previous activity, here are recommended next steps:
-
-    1. **Review Recent Dashboards**: Check your most-used dashboards for updates
-    2. **Explore New Data**: Look for recently added datasets in your domain
-    3. **Share Insights**: Consider sharing successful analyses with your team
-
-    ## Advanced Techniques
-    - Set up automated alerts for key metrics
-    - Create parameterized dashboards for different audiences
-    - Use SQL Lab for complex custom analyses
-    """
-
-    return guidance
-```
-
-## Combining Tools and Prompts
-
-Extensions can provide both tools and prompts that work together:
-
-```python
-# Tool for data processing
-@tool("analytics_extension.calculate_metrics")
-def calculate_metrics(data: dict) -> dict:
-    """Calculate advanced analytics metrics."""
-    # Implementation here
-    pass
-
-# Prompt that guides users to the tool
-@prompt("analytics_extension.metrics_guide")
-async def metrics_guide(ctx: Context) -> str:
-    """Guide users through advanced metrics calculation."""
-    return """
-    # Advanced Metrics Calculation
-
-    Use the `calculate_metrics` tool to compute specialized analytics:
-
-    ## Available Metrics
-    - Customer Lifetime Value (CLV)
-    - Cohort Retention Rates
-    - Statistical Significance Tests
-    - Predictive Trend Analysis
-
-    ## Usage
-    Call the tool with your dataset to get detailed calculations
-    and recommendations for visualization approaches.
-
-    Would you like to calculate metrics for your current dataset?
-    """
-```
-
-## Next Steps
-
-- **[Development](./development)** - Project structure, APIs, and dev workflow
-- **[Security](./security)** - Security best practices for extensions

docs/developer_portal/extensions/overview.md

@@ -1,5 +1,5 @@
 ---
-title: Overview
+title: Extensions Overview
 sidebar_position: 1
 ---
 
@@ -22,32 +22,57 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Overview
+# Extensions Overview
 
-Apache Superset's extension system enables organizations to build custom features without modifying the core codebase. Inspired by the [VS Code extension model](https://code.visualstudio.com/api), this architecture addresses a long-standing challenge: teams previously had to fork Superset or make invasive modifications to add capabilities like query optimizers, custom panels, or specialized integrations—resulting in maintenance overhead and codebase fragmentation.
-
-The extension system introduces a modular, plugin-based architecture where both built-in features and external extensions use the same well-defined APIs. This "lean core" approach ensures that any capability available to Superset's internal features is equally accessible to community-developed extensions, fostering a vibrant ecosystem while reducing the maintenance burden on core contributors.
+Apache Superset's extension system allows developers to enhance and customize Superset's functionality through a modular, plugin-based architecture. Extensions can add new visualization types, custom UI components, data processing capabilities, and integration points.
 
 ## What are Superset Extensions?
 
-Superset extensions are self-contained `.supx` packages that extend the platform's capabilities through standardized contribution points. Each extension can include both frontend (React/TypeScript) and backend (Python) components, bundled together and loaded dynamically at runtime using Webpack Module Federation.
+Superset extensions are self-contained packages that extend the core platform's capabilities. They follow a standardized architecture that ensures compatibility, security, and maintainability while providing powerful customization options.
+
+## Extension Architecture
+
+- **[Architectural Principles](./architectural-principles)** - Core design principles guiding extension development
+- **[High-level Architecture](./high-level-architecture)** - System overview and component relationships
+- **[Extension Project Structure](./extension-project-structure)** - Standard project layout and organization
+- **[Extension Metadata](./extension-metadata)** - Configuration and manifest structure
+
+## Development Guide
+
+- **[Frontend Contribution Types](./frontend-contribution-types)** - Types of UI contributions available
+- **[Interacting with Host](./interacting-with-host)** - Communication patterns with Superset core
+- **[Dynamic Module Loading](./dynamic-module-loading)** - Runtime loading and dependency management
+- **[Development Mode](./development-mode)** - Tools and workflows for extension development
+
+## Deployment & Management
+
+- **[Deploying Extension](./deploying-extension)** - Packaging and distribution strategies
+- **[Lifecycle Management](./lifecycle-management)** - Installation, updates, and removal
+- **[Versioning](./versioning)** - Version management and compatibility
+- **[Security Implications](./security-implications)** - Security considerations and best practices
+
+## Hands-on Examples
+
+- **[Proof of Concept](./proof-of-concept)** - Complete Hello World extension walkthrough
 
 ## Extension Capabilities
 
 Extensions can provide:
 
-- **Custom UI Components**: New panels, views, and interactive elements
-- **Commands and Menus**: Custom actions accessible via menus and keyboard shortcuts
-- **REST API Endpoints**: Backend services under the `/api/v1/extensions/` namespace
-- **MCP Tools and Prompts**: AI agent capabilities for enhanced user assistance
+- **Custom Visualizations**: New chart types and data visualization components
+- **UI Enhancements**: Custom dashboards, panels, and interactive elements  
+- **Data Connectors**: Integration with external data sources and APIs
+- **Workflow Automation**: Custom actions and batch processing capabilities
+- **Authentication Providers**: SSO and custom authentication mechanisms
+- **Theme Customization**: Custom styling and branding options
 
-## Next Steps
+## Getting Started
 
-- **[Quick Start](./quick-start)** - Build your first extension with a complete walkthrough
-- **[Architecture](./architecture)** - Design principles and system overview
-- **[Contribution Types](./contribution-types)** - Available extension points
-- **[Development](./development)** - Project structure, APIs, and development workflow
-- **[Deployment](./deployment)** - Packaging and deploying extensions
-- **[MCP Integration](./mcp)** - Adding AI agent capabilities using extensions
-- **[Security](./security)** - Security considerations and best practices
-- **[Community Extensions](./registry)** - Browse extensions shared by the community
+1. **Learn the Architecture**: Start with [Architectural Principles](./architectural-principles) to understand the design philosophy
+2. **Set up Development**: Follow the [Development Mode](./development-mode) guide to configure your environment
+3. **Build Your First Extension**: Complete the [Proof of Concept](./proof-of-concept) tutorial
+4. **Deploy and Share**: Use the [Deploying Extension](./deploying-extension) guide to package your extension
+
+## Extension Ecosystem
+
+The extension system is designed to foster a vibrant ecosystem of community-contributed functionality. By following the established patterns and guidelines, developers can create extensions that seamlessly integrate with Superset while maintaining the platform's reliability and performance standards.

docs/developer_portal/extensions/proof-of-concept.md

@@ -0,0 +1,288 @@
+---
+title: "Example: Hello World"
+sidebar_position: 14
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Example: Hello World
+
+:::warning Work in Progress
+This documentation is under active development. Some features described may not be fully implemented yet.
+:::
+
+This guide walks you through creating your first Superset extension - a simple "Hello World" panel for SQL Lab. You'll learn how to create, build, package, install, and test a basic extension.
+
+## Prerequisites
+
+Before starting, ensure you have:
+- Node.js 18+ and npm installed
+- Python 3.9+ installed
+- A running Superset development environment with `ENABLE_EXTENSIONS = True` in your config
+- Basic knowledge of React and TypeScript
+
+## Step 1: Initialize Your Extension
+
+First, install the Superset extension CLI and create a new extension project:
+
+```bash
+# Install the CLI globally
+pip install apache-superset-extensions-cli
+
+# Create a new extension
+superset-extensions init hello-world
+cd hello-world
+```
+
+This creates the following structure:
+```
+hello-world/
+├── extension.json         # Extension metadata
+├── frontend/             # Frontend code
+│   ├── src/
+│   │   └── index.tsx    # Main entry point
+│   ├── package.json
+│   └── webpack.config.js
+├── backend/              # Backend code (optional)
+│   └── src/
+└── README.md
+```
+
+## Step 2: Configure Extension Metadata
+
+Edit `extension.json` to define your extension's capabilities:
+
+```json
+{
+  "name": "hello_world",
+  "displayName": "Hello World Extension",
+  "version": "1.0.0",
+  "description": "A simple Hello World panel for SQL Lab",
+  "author": "Your Name",
+  "license": "Apache-2.0",
+  "superset": {
+    "minVersion": "4.0.0"
+  },
+  "frontend": {
+    "contributions": {
+      "views": {
+        "sqllab.panels": [
+          {
+            "id": "hello_world.main",
+            "name": "Hello World",
+            "icon": "SmileOutlined"
+          }
+        ]
+      },
+      "commands": [
+        {
+          "command": "hello_world.greet",
+          "title": "Say Hello",
+          "description": "Display a greeting message"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Step 3: Create the Frontend Component
+
+Create `frontend/src/HelloWorldPanel.tsx`:
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { Card, Button, Alert } from '@apache-superset/core';
+
+export const HelloWorldPanel: React.FC = () => {
+  const [greeting, setGreeting] = useState('Hello, Superset!');
+  const [queryCount, setQueryCount] = useState(0);
+
+  // Listen for query executions
+  useEffect(() => {
+    const handleQueryRun = () => {
+      setQueryCount(prev => prev + 1);
+      setGreeting(`Hello! You've run ${queryCount + 1} queries.`);
+    };
+
+    // Subscribe to SQL Lab events
+    const disposable = window.superset?.sqlLab?.onDidQueryRun?.(handleQueryRun);
+
+    return () => disposable?.dispose?.();
+  }, [queryCount]);
+
+  return (
+    <Card title="Hello World Extension">
+      <Alert
+        message={greeting}
+        type="success"
+        showIcon
+      />
+      <p style={{ marginTop: 16 }}>
+        This is your first Superset extension! 🎉
+      </p>
+      <p>
+        Queries executed this session: <strong>{queryCount}</strong>
+      </p>
+      <Button
+        onClick={() => setGreeting('Hello from the button!')}
+        style={{ marginTop: 16 }}
+      >
+        Click Me
+      </Button>
+    </Card>
+  );
+};
+```
+
+## Step 4: Set Up the Entry Point
+
+Update `frontend/src/index.tsx`:
+
+```tsx
+import { ExtensionContext } from '@apache-superset/core';
+import { HelloWorldPanel } from './HelloWorldPanel';
+
+export function activate(context: ExtensionContext) {
+  console.log('Hello World extension is activating!');
+
+  // Register the panel
+  const panel = context.registerView(
+    'hello_world.main',
+    <HelloWorldPanel />
+  );
+
+  // Register the command
+  const command = context.registerCommand('hello_world.greet', {
+    execute: () => {
+      console.log('Hello from the command!');
+      // You could trigger panel updates or show notifications here
+    }
+  });
+
+  // Add disposables for cleanup
+  context.subscriptions.push(panel, command);
+}
+
+export function deactivate() {
+  console.log('Hello World extension is deactivating!');
+}
+```
+
+## Step 5: Build the Extension
+
+Build your extension assets:
+
+```bash
+# Install dependencies
+cd frontend
+npm install
+
+# Build the extension
+cd ..
+superset-extensions build
+
+# This creates a dist/ folder with your built assets
+```
+
+> **Note:** The `superset-extensions` CLI handles webpack configuration automatically. Superset already has Module Federation configured, so you don't need to set up webpack yourself unless you have specific advanced requirements.
+
+## Step 6: Package the Extension
+
+Create the distributable `.supx` file:
+
+```bash
+superset-extensions bundle
+
+# This creates hello_world-1.0.0.supx
+```
+
+## Step 7: Install in Superset
+
+Upload your extension to a running Superset instance:
+
+### Option A: Via API
+```bash
+curl -X POST http://localhost:8088/api/v1/extensions/import/ \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -F "bundle=@hello_world-1.0.0.supx"
+```
+
+### Option B: Via UI
+1. Navigate to Settings → Extensions
+2. Click "Upload Extension"
+3. Select your `hello_world-1.0.0.supx` file
+4. Click "Install"
+
+## Step 9: Test Your Extension
+
+1. Open SQL Lab in Superset
+2. Look for the "Hello World" panel in the panels dropdown or sidebar
+3. The panel should display your greeting message
+4. Run a SQL query and watch the query counter increment
+5. Click the button to see the greeting change
+
+## Step 10: Development Mode (Optional)
+
+For faster development iteration, use local development mode:
+
+1. Add to your `superset_config.py`:
+```python
+LOCAL_EXTENSIONS = [
+    "/path/to/hello-world"
+]
+ENABLE_EXTENSIONS = True
+```
+
+2. Run the extension in watch mode:
+```bash
+superset-extensions dev
+```
+
+3. Changes will be reflected immediately without rebuilding
+
+## Troubleshooting
+
+### Extension Not Loading
+- Check that `ENABLE_EXTENSIONS = True` in your Superset config
+- Verify the extension is listed in Settings → Extensions
+- Check browser console for errors
+- Ensure all dependencies are installed
+
+### Build Errors
+- Make sure you have the correct Node.js version (18+)
+- Clear node_modules and reinstall: `rm -rf node_modules && npm install`
+- Check that webpack.config.js is properly configured
+
+### Panel Not Visible
+- Verify the contribution point in extension.json matches `sqllab.panels`
+- Check that the panel ID is unique
+- Restart Superset after installing the extension
+
+## Next Steps
+
+Now that you have a working Hello World extension, you can:
+- Add more complex UI components
+- Integrate with Superset's API to fetch data
+- Add backend functionality for data processing
+- Create custom commands and menu items
+- Listen to more SQL Lab events
+
+For more advanced examples, explore the other pages in this documentation section.

docs/developer_portal/extensions/quick-start.md

@@ -1,514 +0,0 @@
----
-title: Quick Start
-sidebar_position: 2
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Quick Start
-
-This guide walks you through creating your first Superset extension - a simple "Hello World" panel that displays a message fetched from a backend API endpoint. You'll learn the essential structure and patterns for building full-stack Superset extensions.
-
-## Prerequisites
-
-Before starting, ensure you have:
-
-- Node.js and npm compatible with your Superset version
-- Python compatible with your Superset version
-- A running Superset development environment
-- Basic knowledge of React, TypeScript, and Flask
-
-## Step 1: Install the Extensions CLI
-
-First, install the Apache Superset Extensions CLI:
-
-```bash
-pip install apache-superset-extensions-cli
-```
-
-## Step 2: Create a New Extension
-
-Use the CLI to scaffold a new extension project. Extensions can include frontend functionality, backend functionality, or both, depending on your needs. This quickstart demonstrates a full-stack extension with both frontend UI components and backend API endpoints to show the complete integration pattern.
-
-```bash
-superset-extensions init
-```
-
-The CLI will prompt you for information:
-
-```
-Extension ID (unique identifier, alphanumeric only): hello_world
-Extension name (human-readable display name): Hello World
-Initial version [0.1.0]: 0.1.0
-License [Apache-2.0]: Apache-2.0
-Include frontend? [Y/n]: Y
-Include backend? [Y/n]: Y
-```
-
-This creates a complete project structure:
-
-```
-hello_world/
-├── extension.json           # Extension metadata and configuration
-├── backend/                 # Backend Python code
-│   ├── src/
-│   │   └── hello_world/
-│   │       ├── __init__.py
-│   │       └── entrypoint.py  # Backend registration
-│   └── pyproject.toml
-└── frontend/                # Frontend TypeScript/React code
-    ├── src/
-    │   └── index.tsx        # Frontend entry point
-    ├── package.json
-    ├── tsconfig.json
-    └── webpack.config.js
-```
-
-## Step 3: Configure Extension Metadata
-
-The generated `extension.json` contains basic metadata. Update it to register your panel in SQL Lab:
-
-```json
-{
-  "id": "hello_world",
-  "name": "Hello World",
-  "version": "0.1.0",
-  "license": "Apache-2.0",
-  "frontend": {
-    "contributions": {
-      "views": {
-        "sqllab.panels": [
-          {
-            "id": "hello_world.main",
-            "name": "Hello World"
-          }
-        ]
-      }
-    },
-    "moduleFederation": {
-      "exposes": ["./index"]
-    }
-  },
-  "backend": {
-    "entryPoints": ["hello_world.entrypoint"],
-    "files": ["backend/src/hello_world/**/*.py"]
-  },
-  "permissions": ["can_read"]
-}
-```
-
-**Key fields:**
-
-- `frontend.contributions.views.sqllab.panels`: Registers your panel in SQL Lab
-- `backend.entryPoints`: Python modules to load eagerly when extension starts
-
-## Step 4: Create Backend API
-
-The CLI generated a basic `backend/src/hello_world/entrypoint.py`. We'll create an API endpoint.
-
-**Create `backend/src/hello_world/api.py`**
-
-```python
-from flask import Response
-from flask_appbuilder.api import expose, protect, safe
-from superset_core.api.rest_api import RestApi
-
-
-class HelloWorldAPI(RestApi):
-    resource_name = "hello_world"
-    openapi_spec_tag = "Hello World"
-    class_permission_name = "hello_world"
-
-    @expose("/message", methods=("GET",))
-    @protect()
-    @safe
-    def get_message(self) -> Response:
-        """Gets a hello world message
-        ---
-        get:
-          description: >-
-            Get a hello world message from the backend
-          responses:
-            200:
-              description: Hello world message
-              content:
-                application/json:
-                  schema:
-                    type: object
-                    properties:
-                      result:
-                        type: object
-                        properties:
-                          message:
-                            type: string
-            401:
-              $ref: '#/components/responses/401'
-        """
-        return self.response(
-            200,
-            result={"message": "Hello from the backend!"}
-        )
-```
-
-**Key points:**
-
-- Extends `RestApi` from `superset_core.api.types.rest_api`
-- Uses Flask-AppBuilder decorators (`@expose`, `@protect`, `@safe`)
-- Returns responses using `self.response(status_code, result=data)`
-- The endpoint will be accessible at `/extensions/hello_world/message`
-- OpenAPI docstrings are crucial - Flask-AppBuilder uses them to automatically generate interactive API documentation at `/swagger/v1`, allowing developers to explore endpoints, understand schemas, and test the API directly from the browser
-
-**Update `backend/src/hello_world/entrypoint.py`**
-
-Replace the generated print statement with API registration:
-
-```python
-from superset_core.api import rest_api
-
-from .api import HelloWorldAPI
-
-rest_api.add_extension_api(HelloWorldAPI)
-```
-
-This registers your API with Superset when the extension loads.
-
-## Step 5: Create Frontend Component
-
-The CLI generates the frontend configuration files. Below are the key configurations that enable Module Federation integration with Superset.
-
-**`frontend/package.json`**
-
-The `@apache-superset/core` package must be listed in both `peerDependencies` (to declare runtime compatibility) and `devDependencies` (to provide TypeScript types during build):
-
-```json
-{
-  "name": "hello_world",
-  "version": "0.1.0",
-  "private": true,
-  "license": "Apache-2.0",
-  "scripts": {
-    "start": "webpack serve --mode development",
-    "build": "webpack --stats-error-details --mode production"
-  },
-  "peerDependencies": {
-    "@apache-superset/core": "^x.x.x",
-    "react": "^x.x.x",
-    "react-dom": "^x.x.x"
-  },
-  "devDependencies": {
-    "@apache-superset/core": "^x.x.x",
-    "@types/react": "^x.x.x",
-    "ts-loader": "^x.x.x",
-    "typescript": "^x.x.x",
-    "webpack": "^5.x.x",
-    "webpack-cli": "^x.x.x",
-    "webpack-dev-server": "^x.x.x"
-  }
-}
-```
-
-**`frontend/webpack.config.js`**
-
-The webpack configuration requires specific settings for Module Federation. Key settings include `externalsType: "window"` and `externals` to map `@apache-superset/core` to `window.superset` at runtime, `import: false` for shared modules to use the host's React instead of bundling a separate copy, and `remoteEntry.[contenthash].js` for cache busting:
-
-```javascript
-const path = require("path");
-const { ModuleFederationPlugin } = require("webpack").container;
-const packageConfig = require("./package.json");
-
-module.exports = (env, argv) => {
-  const isProd = argv.mode === "production";
-
-  return {
-    entry: isProd ? {} : "./src/index.tsx",
-    mode: isProd ? "production" : "development",
-    devServer: {
-      port: 3001,
-      headers: {
-        "Access-Control-Allow-Origin": "*",
-      },
-    },
-    output: {
-      filename: isProd ? undefined : "[name].[contenthash].js",
-      chunkFilename: "[name].[contenthash].js",
-      clean: true,
-      path: path.resolve(__dirname, "dist"),
-      publicPath: `/api/v1/extensions/${packageConfig.name}/`,
-    },
-    resolve: {
-      extensions: [".ts", ".tsx", ".js", ".jsx"],
-    },
-    // Map @apache-superset/core imports to window.superset at runtime
-    externalsType: "window",
-    externals: {
-      "@apache-superset/core": "superset",
-    },
-    module: {
-      rules: [
-        {
-          test: /\.tsx?$/,
-          use: "ts-loader",
-          exclude: /node_modules/,
-        },
-      ],
-    },
-    plugins: [
-      new ModuleFederationPlugin({
-        name: packageConfig.name,
-        filename: "remoteEntry.[contenthash].js",
-        exposes: {
-          "./index": "./src/index.tsx",
-        },
-        shared: {
-          react: {
-            singleton: true,
-            requiredVersion: packageConfig.peerDependencies.react,
-            import: false, // Use host's React, don't bundle
-          },
-          "react-dom": {
-            singleton: true,
-            requiredVersion: packageConfig.peerDependencies["react-dom"],
-            import: false,
-          },
-        },
-      }),
-    ],
-  };
-};
-```
-
-**`frontend/tsconfig.json`**
-
-```json
-{
-  "compilerOptions": {
-    "baseUrl": ".",
-    "moduleResolution": "node",
-    "jsx": "react",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true
-  },
-  "include": ["src"]
-}
-```
-
-**Create `frontend/src/HelloWorldPanel.tsx`**
-
-Create a new file for the component implementation:
-
-```tsx
-import React, { useEffect, useState } from 'react';
-import { authentication } from '@apache-superset/core';
-
-const HelloWorldPanel: React.FC = () => {
-  const [message, setMessage] = useState<string>('');
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string>('');
-
-  useEffect(() => {
-    const fetchMessage = async () => {
-      try {
-        const csrfToken = await authentication.getCSRFToken();
-        const response = await fetch('/extensions/hello_world/message', {
-          method: 'GET',
-          headers: {
-            'Content-Type': 'application/json',
-            'X-CSRFToken': csrfToken!,
-          },
-        });
-
-        if (!response.ok) {
-          throw new Error(`Server returned ${response.status}`);
-        }
-
-        const data = await response.json();
-        setMessage(data.result.message);
-      } catch (err) {
-        setError(err instanceof Error ? err.message : 'An error occurred');
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchMessage();
-  }, []);
-
-  if (loading) {
-    return (
-      <div style={{ padding: '20px', textAlign: 'center' }}>
-        <p>Loading...</p>
-      </div>
-    );
-  }
-
-  if (error) {
-    return (
-      <div style={{ padding: '20px', color: 'red' }}>
-        <strong>Error:</strong> {error}
-      </div>
-    );
-  }
-
-  return (
-    <div style={{ padding: '20px' }}>
-      <h3>Hello World Extension</h3>
-      <div
-        style={{
-          padding: '16px',
-          backgroundColor: '#f6ffed',
-          border: '1px solid #b7eb8f',
-          borderRadius: '4px',
-          marginBottom: '16px',
-        }}
-      >
-        <strong>{message}</strong>
-      </div>
-      <p>This message was fetched from the backend API! 🎉</p>
-    </div>
-  );
-};
-
-export default HelloWorldPanel;
-```
-
-**Update `frontend/src/index.tsx`**
-
-Replace the generated code with the extension entry point:
-
-```tsx
-import React from 'react';
-import { core } from '@apache-superset/core';
-import HelloWorldPanel from './HelloWorldPanel';
-
-export const activate = (context: core.ExtensionContext) => {
-  context.disposables.push(
-    core.registerViewProvider('hello_world.main', () => <HelloWorldPanel />),
-  );
-};
-
-export const deactivate = () => {};
-```
-
-**Key patterns:**
-
-- `activate` function is called when the extension loads
-- `core.registerViewProvider` registers the component with ID `hello_world.main` (matching `extension.json`)
-- `authentication.getCSRFToken()` retrieves the CSRF token for API calls
-- Fetch calls to `/extensions/{extension_id}/{endpoint}` reach your backend API
-- `context.disposables.push()` ensures proper cleanup
-
-## Step 6: Install Dependencies
-
-Install the frontend dependencies:
-
-```bash
-cd frontend
-npm install
-cd ..
-```
-
-## Step 7: Package the Extension
-
-Create a `.supx` bundle for deployment:
-
-```bash
-superset-extensions bundle
-```
-
-This command automatically:
-
-- Builds frontend assets using Webpack with Module Federation
-- Collects backend Python source files
-- Creates a `dist/` directory with:
-  - `manifest.json` - Build metadata and asset references
-  - `frontend/dist/` - Built frontend assets (remoteEntry.js, chunks)
-  - `backend/` - Python source files
-- Packages everything into `hello_world-0.1.0.supx` - a zip archive with the specific structure required by Superset
-
-## Step 8: Deploy to Superset
-
-To deploy your extension, you need to enable extensions support and configure where Superset should load them from.
-
-**Configure Superset**
-
-Add the following to your `superset_config.py`:
-
-```python
-# Enable extensions feature
-FEATURE_FLAGS = {
-    "EXTENSIONS": True,
-}
-
-# Set the directory where extensions are stored
-EXTENSIONS_PATH = "/path/to/extensions/folder"
-```
-
-**Copy Extension Bundle**
-
-Copy your `.supx` file to the configured extensions path:
-
-```bash
-cp hello_world-0.1.0.supx /path/to/extensions/folder/
-```
-
-**Restart Superset**
-
-Restart your Superset instance to load the extension:
-
-```bash
-# Restart your Superset server
-superset run
-```
-
-Superset will extract and validate the extension metadata, load the assets, register the extension with its capabilities, and make it available for use.
-
-## Step 9: Test Your Extension
-
-1. **Open SQL Lab** in Superset
-2. Look for the **"Hello World"** panel in the panels dropdown or sidebar
-3. Open the panel - it should display "Hello from the backend!"
-4. Check that the message was fetched from your API endpoint
-
-## Understanding the Flow
-
-Here's what happens when your extension loads:
-
-1. **Superset starts**: Reads `extension.json` and loads backend entrypoint
-2. **Backend registration**: `entrypoint.py` registers your API via `rest_api.add_extension_api()`
-3. **Frontend loads**: When SQL Lab opens, Superset fetches the remote entry file
-4. **Module Federation**: Webpack loads your extension code and resolves `@apache-superset/core` to `window.superset`
-5. **Activation**: `activate()` is called, registering your view provider
-6. **Rendering**: When the user opens your panel, React renders `<HelloWorldPanel />`
-7. **API call**: Component fetches data from `/extensions/hello_world/message`
-8. **Backend response**: Your Flask API returns the hello world message
-9. **Display**: Component shows the message to the user
-
-## Next Steps
-
-Now that you have a working extension, explore:
-
-- **[Development](./development)** - Project structure, APIs, and development workflow
-- **[Contribution Types](./contribution-types)** - Other contribution points beyond panels
-- **[Deployment](./deployment)** - Packaging and deploying your extension
-- **[Security](./security)** - Security best practices for extensions
-
-For a complete real-world example, examine the query insights extension in the Superset codebase.

docs/developer_portal/extensions/registry.md

@@ -1,47 +0,0 @@
----
-title: Community Extensions
-sidebar_position: 9
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements.  See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership.  The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License.  You may obtain a copy of the License at
-
-  http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied.  See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Community Extensions
-
-This page serves as a registry of community-created Superset extensions. These extensions are developed and maintained by community members and are not officially supported or vetted by the Apache Superset project. **Before installing any community extension, administrators are responsible for evaluating the extension's source code for security vulnerabilities, performance impact, UI/UX quality, and compatibility with their Superset deployment.**
-
-## Extensions
-
-| Name                                                                                                      | Description                                                                                                                                                                                                                                         | Author            | Preview                                                                                                                                                 |
-| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Extensions API Explorer](https://github.com/michael-s-molina/superset-extensions/tree/main/api_explorer) | A SQL Lab panel that demonstrates the Extensions API by providing an interactive explorer for testing commands like getTabs, getCurrentTab, and getDatabases. Useful for extension developers to understand and experiment with the available APIs. | Michael S. Molina | <a href="/img/extensions/api_explorer.png" target="_blank"><img src="/img/extensions/api_explorer.png" alt="Extensions API Explorer" width="120" /></a> |
-| [SQL Query Flow Visualizer](https://github.com/msyavuz/superset-sql-visualizer) | A SQL Lab panel that transforms SQL queries into interactive flow diagrams, helping developers and analysts understand query execution paths and data relationships.| Mehmet Salih Yavuz | <a href="/img/extensions/sql_flow_visualizer.png" target="_blank"><img src="/img/extensions/sql_flow_visualizer.png" alt="SQL Flow Visualizer" width="120" /></a> |
-## How to Add Your Extension
-
-To add your extension to this registry, submit a pull request to the [Apache Superset repository](https://github.com/apache/superset) with the following changes:
-
-1. Add a row to the **Extensions** table above using this format:
-
-```markdown
-| [Your Extension](https://github.com/your-username/your-repo) | A brief description of your extension. | Your Name | <a href="/img/extensions/your-screenshot.png" target="_blank"><img src="/img/extensions/your-screenshot.png" alt="Your Extension" width="120" /></a> |
-```
-
-2. Add a screenshot to `docs/static/img/extensions/` (recommended size: 800x450px, PNG or JPG format)
-
-3. Submit your PR with a title like "docs: Add [Extension Name] to community extensions registry"

docs/developer_portal/extensions/security-implications.md

@@ -1,6 +1,6 @@
 ---
-title: Security
-sidebar_position: 8
+title: Security Implications and Responsibilities
+sidebar_position: 12
 ---
 
 <!--
@@ -22,14 +22,12 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-# Security
+# Security Implications and Responsibilities
 
 By default, extensions are disabled and must be explicitly enabled by setting the `ENABLE_EXTENSIONS` feature flag. Built-in extensions are included as part of the Superset codebase and are held to the same security standards and review processes as the rest of the application.
 
 For external extensions, administrators are responsible for evaluating and verifying the security of any extensions they choose to install, just as they would when installing third-party NPM or PyPI packages. At this stage, all extensions run in the same context as the host application, without additional sandboxing. This means that external extensions can impact the security and performance of a Superset environment in the same way as any other installed dependency.
 
-We plan to introduce an optional sandboxed execution model for extensions in the future (as part of an additional SIP). Until then, administrators should exercise caution and follow best practices when selecting and deploying third-party extensions. A directory of community extensions is available in the [Community Extensions](./registry) page. Note that these extensions are not vetted by the Apache Superset project—administrators must evaluate each extension before installation.
+We plan to introduce an optional sandboxed execution model for extensions in the future (as part of an additional SIP). Until then, administrators should exercise caution and follow best practices when selecting and deploying third-party extensions. A directory of known Superset extensions may be maintained in a means similar to [this page](https://github.com/apache/superset/wiki/Superset-Third%E2%80%90Party-Plugins-Directory) on the wiki. We also discussed the possibility of introducing a shared registry for vetted extensions but decided to leave it out of the initial scope of the project. We might introduce a registry at a later stage depending on the evolution of extensions created by the community.
 
-**Any performance or security vulnerabilities introduced by external extensions should be reported directly to the extension author, not as Superset vulnerabilities.**
-
-Any security concerns regarding built-in extensions (included in Superset's monorepo) should be reported to the Superset Security mailing list for triage and resolution by maintainers.
+Any performance or security vulnerabilities introduced by external extensions should be reported directly to the extension author, not as Superset vulnerabilities. Any security concerns regarding built-in extensions (included in Superset's monorepo) should be reported to the Superset Security mailing list for triage and resolution by maintainers.

docs/developer_portal/extensions/versioning.md

@@ -0,0 +1,31 @@
+---
+title: Versioning
+sidebar_position: 11
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Versioning
+
+All core packages published to NPM and PyPI—including `@apache-superset/core`, `apache-superset-core`, and `apache-superset-extensions-cli`—will follow semantic versioning ([semver](https://semver.org/)). This means that any breaking changes to public APIs, interfaces, or extension points will result in a major version bump, while new features and non-breaking changes will be released as minor or patch updates.
+
+During the initial development phase, packages will remain under version 0.x, allowing for rapid iteration and the introduction of breaking changes as the architecture evolves based on real-world feedback. Once the APIs and extension points are considered stable, we will release version 1.0.0 and begin enforcing strict server practices.
+
+To minimize disruption, breaking changes will be carefully planned and communicated in advance. We will provide clear migration guides and changelogs to help extension authors and core contributors adapt to new versions. Where possible, we will deprecate APIs before removing them, giving developers time to transition to newer interfaces.

docs/developer_portal/guides/command-palette.md

@@ -0,0 +1,61 @@
+---
+title: Command Palette Integration
+sidebar_position: 2
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Command Palette Integration
+
+🚧 **Coming Soon** 🚧
+
+Learn how to integrate your plugin with Superset's command palette to provide quick access to plugin functionality.
+
+## Topics to be covered:
+
+- Understanding the command palette architecture
+- Registering custom commands
+- Command categories and organization
+- Keyboard shortcuts and hotkeys
+- Dynamic command generation
+- Command context and availability
+- Icon and description customization
+- Command execution and callbacks
+- Search and filtering integration
+- Command palette theming
+
+## Command Types
+
+- **Navigation commands** - Quick navigation to plugin views
+- **Action commands** - Execute plugin-specific actions
+- **Creation commands** - Create new charts, dashboards, or data sources
+- **Configuration commands** - Quick access to settings
+- **Help commands** - Documentation and support links
+
+## Implementation Patterns
+
+- Command registration lifecycle
+- Async command execution
+- Context-aware command availability
+- Command result handling
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/guides/custom-editors.md

@@ -0,0 +1,64 @@
+---
+title: Custom Editors
+sidebar_position: 4
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Custom Editors
+
+🚧 **Coming Soon** 🚧
+
+Build specialized editing interfaces for data manipulation, query building, and configuration management.
+
+## Topics to be covered:
+
+- Editor component architecture
+- Syntax highlighting and code completion
+- Real-time validation and error detection
+- Undo/redo functionality
+- Collaborative editing features
+- Custom language support
+- Editor extensions and plugins
+- Integration with Superset's SQL Lab
+- File and document management
+- Export and import capabilities
+
+## Editor Types
+
+- **SQL query editors** - Enhanced database query interfaces
+- **Configuration editors** - JSON, YAML, and custom config formats
+- **Formula editors** - Mathematical and business logic expressions
+- **Chart configuration** - Visual chart property editors
+- **Data transformation** - ETL pipeline builders
+- **Dashboard layout editors** - Drag-and-drop interface builders
+
+## Advanced Features
+
+- Monaco Editor integration
+- CodeMirror customization
+- Custom language definitions
+- Intelligent autocomplete
+- Syntax error highlighting
+- Multi-cursor editing
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/guides/overview.md

@@ -0,0 +1,58 @@
+---
+title: Development Guides Overview
+sidebar_position: 1
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Development Guides Overview
+
+🚧 **Coming Soon** 🚧
+
+This section contains practical guides and tutorials for common plugin development scenarios and advanced techniques.
+
+## Topics to be covered:
+
+- Step-by-step development tutorials
+- Common development patterns and solutions
+- Integration with Superset's core features
+- Advanced plugin architectures
+- Performance optimization techniques
+- Debugging and troubleshooting guides
+- Migration guides for plugin updates
+- Best practices and coding standards
+
+## Available Guides
+
+- **Command Palette Integration** - Add custom commands and shortcuts
+- **WebViews and Embedded Content** - Display external content in Superset
+- **Custom Editors** - Build specialized data editing interfaces
+- **Virtual Documents** - Handle dynamic content and data sources
+
+## Guide Categories
+
+- **Beginner** - Getting started with basic concepts
+- **Intermediate** - Common patterns and integrations
+- **Advanced** - Complex architectures and performance optimization
+- **Troubleshooting** - Debugging and problem-solving
+
+---
+
+*This documentation is under active development. Check back soon for updates!*

docs/developer_portal/guides/virtual-documents.md

@@ -0,0 +1,63 @@
+---
+title: Virtual Documents
+sidebar_position: 5
+---
+
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License.  You may obtain a copy of the License at
+
+  http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Virtual Documents
+
+🚧 **Coming Soon** 🚧
+
+Learn how to create and manage virtual documents that represent dynamic content and data sources within Superset.
+
+## Topics to be covered:
+
+- Virtual document concepts and architecture
+- Dynamic content generation
+- Document lifecycle management
+- Data source abstraction
+- Real-time document updates
+- Document caching and performance
+- Version control and history
+- Collaborative document editing
+- Document search and indexing
+- Export and sharing capabilities
+
+## Virtual Document Types
+
+- **Dynamic reports** - Auto-updating analytical reports
+- **Data lineage documents** - Interactive data flow visualization
+- **Configuration schemas** - Dynamic form generation
+- **API documentation** - Auto-generated from code
+- **Data dictionaries** - Searchable metadata catalogs
+- **Query libraries** - Shared SQL query collections
+
+## Implementation Patterns
+
+- Document provider interfaces
+- Content resolution strategies
+- Change detection and synchronization
+- Document serialization formats
+- Access control and permissions
+
+---
+
+*This documentation is under active development. Check back soon for updates!*