feat(showcase): add runnable Vue documentation (#6222)

## What this adds

Vue users should be able to follow the same documentation journeys as
React users, with examples that match the Vue package they can install
today.

This PR adds a runnable Vue chat application to Showcase and makes the
website the home for Vue guides and API reference. It follows the
existing React and Angular setup rather than introducing a separate
documentation system.

- **Showcase:** one Vue application and build artifact, integrated with
the existing backend catalog, hosting, and validation. Only
`agentic-chat` is enabled; unsupported combinations stay unavailable.
- **Guides:** React-aligned Vue examples, shared explanations where the
behavior is framework-neutral, and explicit notes where Vue currently
differs.
- **Reference and discovery:** updated Vue API pages, navigation derived
from the React structure, and Vue-aware links, search, sitemap, and
Markdown/LLM output.

This does not add Vue runtime features, resolve existing package type
errors, define A2UI or v1 compatibility, or change shared server-side
authorization examples.

## How to review

The eight commits keep the Vue host, hosting and build integration,
validation, API reference, guides, package entry point, synchronization
policy, and reviewer corrections separate.

The main review questions are whether the Showcase integration follows
the existing frontend pattern, and whether the Vue docs differ from
React only where the current Vue implementation requires it.

Author: BenTaylorDev

.github/config-allowlist.txt

@@ -137,3 +137,4 @@ showcase/shell-dashboard/next.config.ts
 showcase/shell-docs/next.config.ts
 showcase/shell-dojo/next.config.ts
 showcase/shell/next.config.ts
+showcase/vue/vite.config.ts

.github/workflows/showcase_build.yml

@@ -40,7 +40,9 @@ on:
       - "packages/angular/**"
       - "packages/core/**"
       - "packages/shared/**"
+      - "packages/vue/**"
       - "packages/web-components/**"
+      - "packages/web-inspector/**"
       - ".github/workflows/showcase_build.yml"
       - ".github/workflows/showcase_build_check.yml"
   workflow_dispatch:
@@ -120,6 +122,7 @@ jobs:
       matrix: ${{ steps.build-matrix.outputs.matrix }}
       has_changes: ${{ steps.build-matrix.outputs.has_changes }}
       needs_angular: ${{ steps.build-matrix.outputs.needs_angular }}
+      needs_vue: ${{ steps.build-matrix.outputs.needs_vue }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -149,6 +152,13 @@ jobs:
               - 'packages/core/**'
               - 'packages/shared/**'
               - 'packages/web-components/**'
+            vue:
+              - 'showcase/vue/**'
+              - 'packages/core/**'
+              - 'packages/shared/**'
+              - 'packages/vue/**'
+              - 'packages/web-components/**'
+              - 'packages/web-inspector/**'
             shell:
               - 'showcase/shell/**'
               - 'showcase/shared/**'
@@ -362,6 +372,10 @@ jobs:
                 (($changes | index("angular") != null) and (
                   (.context | startswith("showcase/integrations/")) or
                   .dispatch_name == "shell"
+                )) or
+                (($changes | index("vue") != null) and (
+                  (.context | startswith("showcase/integrations/")) or
+                  .dispatch_name == "shell"
                 ))
               ))
             ))]
@@ -393,6 +407,7 @@ jobs:
 
           echo "matrix=$MATRIX" >> $GITHUB_OUTPUT
           echo "needs_angular=$(echo "$MATRIX" | jq -r 'any(.[]; (.context | startswith("showcase/integrations/")))')" >> $GITHUB_OUTPUT
+          echo "needs_vue=$(echo "$MATRIX" | jq -r 'any(.[]; (.context | startswith("showcase/integrations/")))')" >> $GITHUB_OUTPUT
           if [ "$MATRIX" = "[]" ]; then
             echo "has_changes=false" >> $GITHUB_OUTPUT
           else
@@ -500,8 +515,50 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  build-vue:
+    name: Build canonical Vue browser artifact
+    needs: [detect-changes]
+    if: needs.detect-changes.outputs.has_changes == 'true'
+    runs-on: ubuntu-26.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - name: Setup Node
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22.x
+
+      - name: Install
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        run: pnpm nx build @copilotkit/showcase-vue-host
+
+      - name: Upload canonical Vue browser artifact
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: showcase-vue-browser-${{ github.sha }}
+          path: showcase/vue/dist
+          if-no-files-found: error
+          retention-days: 1
+
   build:
-    needs: [detect-changes, check-lockfile, build-angular]
+    needs: [detect-changes, check-lockfile, build-angular, build-vue]
     if: needs.detect-changes.outputs.has_changes == 'true'
     runs-on: depot-ubuntu-24.04-4
     timeout-minutes: ${{ fromJSON(matrix.service.timeout) }}
@@ -541,6 +598,13 @@ jobs:
           name: showcase-angular-browser-${{ github.sha }}
           path: ${{ runner.temp }}/showcase-angular-browser
 
+      - name: Download canonical Vue browser artifact
+        if: startsWith(matrix.service.context, 'showcase/integrations/')
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: showcase-vue-browser-${{ github.sha }}
+          path: ${{ runner.temp }}/showcase-vue-browser
+
       - name: Setup Depot
         uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1
 
@@ -591,6 +655,7 @@ jobs:
       - name: Copy shared modules into build context
         env:
           ANGULAR_BROWSER: ${{ runner.temp }}/showcase-angular-browser
+          VUE_BROWSER: ${{ runner.temp }}/showcase-vue-browser
         run: |
           set -euo pipefail
           CONTEXT="${{ matrix.service.context }}"
@@ -632,6 +697,10 @@ jobs:
             source showcase/scripts/cli/_common.sh
             stage_angular "$CONTEXT" "$ANGULAR_BROWSER"
           fi
+          if [ -L "$CONTEXT/public/vue" ]; then
+            source showcase/scripts/cli/_common.sh
+            stage_vue "$CONTEXT" "$VUE_BROWSER"
+          fi
 
       - name: Build and push
         if: ${{ matrix.service.skip_build != true }}

.github/workflows/showcase_build_check.yml

@@ -17,7 +17,9 @@ on:
       - "packages/angular/**"
       - "packages/core/**"
       - "packages/shared/**"
+      - "packages/vue/**"
       - "packages/web-components/**"
+      - "packages/web-inspector/**"
       - ".github/workflows/showcase_build.yml"
       - ".github/workflows/showcase_build_check.yml"
 
@@ -39,6 +41,7 @@ jobs:
       matrix: ${{ steps.build-matrix.outputs.matrix }}
       has_changes: ${{ steps.build-matrix.outputs.has_changes }}
       needs_angular: ${{ steps.build-matrix.outputs.needs_angular }}
+      needs_vue: ${{ steps.build-matrix.outputs.needs_vue }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
         with:
@@ -86,6 +89,13 @@ jobs:
               - 'packages/core/**'
               - 'packages/shared/**'
               - 'packages/web-components/**'
+            vue:
+              - 'showcase/vue/**'
+              - 'packages/core/**'
+              - 'packages/shared/**'
+              - 'packages/vue/**'
+              - 'packages/web-components/**'
+              - 'packages/web-inspector/**'
             shell:
               - 'showcase/shell/**'
               - 'showcase/shared/**'
@@ -230,12 +240,13 @@ jobs:
           # untrusted PR metadata so branch names are encoded as JSON data,
           # not interpolated into shell source.
           #
-          # A workflow change builds every image, because the edit can break
-          # any build step. An Angular/package change builds NO image by
-          # itself: integration images install PUBLISHED @copilotkit packages
+          # A workflow change builds every image declared here, because the
+          # edit can break any build step. An Angular/Vue/package change builds
+          # NO image by itself: integration images install PUBLISHED @copilotkit packages
           # and their contexts exclude packages/, so the image builds do not
-          # test the PR's package code. The build-angular job still compiles
-          # the Angular host against the PR's packages (needs_angular below).
+          # test the PR's package code. The canonical frontend jobs compile
+          # the affected hosts against the PR's packages. Any integration
+          # image needs both browser artifacts for staging below.
           # The post-merge showcase_build.yml still builds every image.
           MATRIX=$(echo "$ALL_SERVICES" | jq -c --argjson changes "$CHANGES" --arg sha "$PR_HEAD_SHA" --arg ref "$PR_HEAD_REF" '
             [.[] |
@@ -249,6 +260,7 @@ jobs:
 
           echo "matrix=$MATRIX" >> $GITHUB_OUTPUT
           echo "needs_angular=$(echo "$MATRIX" | jq -r --argjson changes "$CHANGES" 'any(.[]; (.context | startswith("showcase/integrations/"))) or ($changes | index("angular") != null)')" >> $GITHUB_OUTPUT
+          echo "needs_vue=$(echo "$MATRIX" | jq -r --argjson changes "$CHANGES" 'any(.[]; (.context | startswith("showcase/integrations/"))) or ($changes | index("vue") != null)')" >> $GITHUB_OUTPUT
           if [ "$MATRIX" = "[]" ]; then
             echo "has_changes=false" >> $GITHUB_OUTPUT
           else
@@ -258,8 +270,8 @@ jobs:
   build-angular:
     name: Build canonical Angular browser artifact
     needs: [detect-changes]
-    # Runs for an Angular/package change even when no image builds, so the
-    # Angular host still compiles against the PR's packages.
+    # Compile for Angular/package changes or integration images. For other
+    # images, run a successful no-op so build-check's needs does not skip them.
     if: needs.detect-changes.outputs.has_changes == 'true' || needs.detect-changes.outputs.needs_angular == 'true'
     runs-on: ubuntu-26.04
     timeout-minutes: 30
@@ -299,8 +311,52 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  build-vue:
+    name: Build canonical Vue browser artifact
+    needs: [detect-changes]
+    # Compile for Vue/package changes or integration images. For other
+    # images, run a successful no-op so build-check's needs does not skip them.
+    if: needs.detect-changes.outputs.has_changes == 'true' || needs.detect-changes.outputs.needs_vue == 'true'
+    runs-on: ubuntu-26.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+
+      - name: Setup Node
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: 22.x
+
+      - name: Install
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Build
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        run: pnpm nx build @copilotkit/showcase-vue-host
+
+      - name: Upload canonical Vue browser artifact
+        if: needs.detect-changes.outputs.needs_vue == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: showcase-vue-browser-${{ github.sha }}
+          path: showcase/vue/dist
+          if-no-files-found: error
+          retention-days: 1
+
   build-check:
-    needs: [detect-changes, build-angular]
+    needs: [detect-changes, build-angular, build-vue]
     if: needs.detect-changes.outputs.has_changes == 'true'
     # Depot builds the image remotely; this GitHub-hosted runner loads it
     # locally and verifies the resulting Node runtime without starting the app.
@@ -339,6 +395,13 @@ jobs:
           name: showcase-angular-browser-${{ github.sha }}
           path: ${{ runner.temp }}/showcase-angular-browser
 
+      - name: Download canonical Vue browser artifact
+        if: startsWith(matrix.service.context, 'showcase/integrations/')
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: showcase-vue-browser-${{ github.sha }}
+          path: ${{ runner.temp }}/showcase-vue-browser
+
       - name: Setup Depot
         uses: depot/setup-action@91bc8495a33ebfc504ffc89e5674379ccf23c29c # v1
 
@@ -362,6 +425,7 @@ jobs:
         if: startsWith(matrix.service.context, 'showcase/integrations/')
         env:
           ANGULAR_BROWSER: ${{ runner.temp }}/showcase-angular-browser
+          VUE_BROWSER: ${{ runner.temp }}/showcase-vue-browser
         run: |
           set -euo pipefail
           CONTEXT="${{ matrix.service.context }}"
@@ -399,6 +463,10 @@ jobs:
             source showcase/scripts/cli/_common.sh
             stage_angular "$CONTEXT" "$ANGULAR_BROWSER"
           fi
+          if [ -L "$CONTEXT/public/vue" ]; then
+            source showcase/scripts/cli/_common.sh
+            stage_vue "$CONTEXT" "$VUE_BROWSER"
+          fi
 
       - name: Login to GHCR for the pinned aimock base
         if: matrix.service.dispatch_name == 'showcase-aimock'

packages/vue/AGENTS.md

@@ -4,14 +4,15 @@ This file defines contributor workflow for keeping `@copilotkit/vue` aligned wit
 
 ## Scope
 
-- Scope is limited to `packages/vue/**`.
-- Keep upstream changes outside the Vue package to a minimum until the Vue port is merged.
+- Package implementation scope is limited to `packages/vue/**`.
+- The documented integration exceptions are Vue docs and runnable examples under `showcase/**`, plus their registry, generated-catalog, and validation-workflow plumbing described in [Documentation ownership](#documentation-ownership).
+- Keep other upstream changes outside the Vue package to a minimum until the Vue port is merged.
 
 ## Parity source of truth
 
 - React remains the canonical behavioral reference: `packages/react-core/`, `packages/react-ui/`, and `packages/react-textarea/`.
 - Use [PARITY.md](./PARITY.md) as the canonical Vue-side parity policy, architectural translation guide, strict test-port rulebook, and living React-to-Vue implementation/test matrix.
-- Keep [README.md](./README.md) focused on user-facing package documentation.
+- Keep [README.md](./README.md) as the slim npm-facing package entry point.
 
 ## Required parity workflow
 
@@ -49,8 +50,8 @@ When touching integration/build behavior:
 
 1. `pnpm nx run @copilotkit/vue:build`
 
-## Documentation placement
+## Documentation ownership
 
-- Parity rules, architectural translation decisions, strict translatability criteria, checklist, and mapping matrix: [PARITY.md](./PARITY.md).
-- Public package usage and API examples: [README.md](./README.md).
-- User-facing visual docs/examples: `examples/v2/vue/storybook/**`.
+- Canonical long-form Vue guides and API reference live in `showcase/shell-docs/src/content/`.
+- Runnable Vue examples live in `showcase/vue/`; feature coverage is owned by `showcase/shared/frontend-registry.json`, generated frontend catalogs, and Showcase validation workflows. See [PARITY.md](./PARITY.md#package-boundary-and-documentation-placement) for the canonical policy.
+- [PARITY.md](./PARITY.md) records parity governance and intentional differences; it is not a duplicate coverage catalog.