@copilotkit/vue 1.81.0 → 1.83.0

package/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.

package/CONTRIBUTOR_GUIDE.md

@@ -0,0 +1,120 @@
+# Contributor guide: keeping Vue in sync with React
+
+Use this guide when changing `@copilotkit/vue`. It describes how to trace a
+React feature into Vue, choose the right kind of translation, and keep behavior,
+tests, and documentation aligned. General setup, branching, commits, and PR
+guidance live in the [root contributing guide](../../CONTRIBUTING.md).
+
+There is no blanket promise of one-to-one API or test parity. React is the
+behavioral reference; Vue should match its behavior with the smallest
+Vue-native differences.
+
+## File responsibilities
+
+| File                       | Reader                     | Purpose                                                                                       |
+| -------------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
+| [`README.md`](./README.md) | npm users                  | Installation, concise usage, and package-facing examples.                                     |
+| `CONTRIBUTOR_GUIDE.md`     | Human contributors         | Practical workflow for keeping Vue aligned with React.                                        |
+| [`AGENTS.md`](./AGENTS.md) | Contributors and agents    | Short, required rules for package scope, reactivity, validation, and ownership.               |
+| [`PARITY.md`](./PARITY.md) | Contributors and reviewers | Detailed translation policy, test-port rules, intentional divergences, and the living matrix. |
+
+Use this guide for orientation. Use `AGENTS.md` for package constraints and
+`PARITY.md` for the rule or matrix row that applies to the feature. Do not copy
+those documents' full policy or coverage table here.
+
+## React references and Vue architecture
+
+React is the canonical behavioral reference in:
+
+- `packages/react-core/`
+- `packages/react-ui/`
+- `packages/react-textarea/`
+
+Vue is one published package, not a parallel `vue-core` plus `vue-ui` split.
+Current V2 code is primarily under `packages/vue/src/v2/`. The root
+[`src/index.ts`](./src/index.ts) also exposes V1 compatibility wrappers from
+`src/hooks/` and `src/components/copilot-provider/`, so check the public barrel
+before adding or moving an export. Framework-agnostic behavior comes from
+`@copilotkit/core`.
+
+Headless React hooks and providers generally translate to Vue composables,
+providers, or types. Render props and render-oriented hooks generally translate
+to composable state plus named or scoped slots. Slots are the primary Vue
+customization model; approved programmatic renderer APIs cover cases such as
+ordered registration or agent scoping.
+
+## Short sync workflow
+
+1. Find the React implementation, public types, dedicated tests, and the matching
+   row in [`PARITY.md`](./PARITY.md). Search the canonical package trees and
+   `packages/vue/src` by public symbol or component name. A matching filename is
+   only a starting point.
+2. Read the React tests before writing Vue code. Record the boundary and behavior
+   they assert so the Vue counterpart tests the same thing.
+3. Classify the feature with the [translation decision tree](./PARITY.md#translation-decision-tree)
+   and [near-100% rule](./PARITY.md#near-100-translation-rule). If a new or
+   expanded Vue API may be needed, discuss that divergence before implementing it.
+4. Implement in the existing Vue source area, keep the relevant barrel exports
+   aligned, and add the Vue counterpart at the same behavioral boundary. For
+   strict ports, follow the detailed [test translation policy](./PARITY.md#test-translation-policy);
+   for slot APIs, follow the [slot-suite policy](./PARITY.md#slot-system-suite-translation-policy).
+5. Update the relevant `PARITY.md` matrix row in the same code change. Use
+   `matched`, `partial`, or `intentional-divergence` honestly. Add package usage
+   notes to `README.md`; route long-form docs and runnable examples to their
+   owners below.
+
+## Expected framework differences versus behavior changes
+
+Expected Vue differences include `ref`/`computed`/`watch` instead of React state
+and effects, Vue lifecycle hooks, templates instead of JSX, and slots instead of
+render props. These are translation mechanics.
+
+Behavioral differences are different precedence or fallback, missing edge-case
+handling, changed lifecycle or error semantics, or unsafe reactive proxies at a
+clone or serialization boundary. Treat those as parity work, not as an automatic
+framework exception. Document intentional differences in [`PARITY.md`](./PARITY.md)
+and preserve the package reactivity rules in [`AGENTS.md`](./AGENTS.md).
+
+## Documentation and Showcase ownership
+
+Package README content is concise. CopilotKit guides, API reference, and reusable
+snippets belong under [`showcase/shell-docs/src/content/`](../../showcase/shell-docs/src/content/);
+the top-level `docs/` path is only a symlink. Follow the repository's
+[documentation guidance](../../.claude/docs/documentation.md), including
+`docs_mode` and `getDocsFolder()` when framework-owned docs are involved.
+
+For showcase-driven docs, edit source inputs such as manifests, shared/root MDX,
+snippets, demos, source regions, or sparse overrides. Do not edit generated
+`showcase/shell-docs/src/data/frameworks/` files. Authored framework docs live in
+their MDX tree and `meta.json`.
+
+Runnable Vue journeys belong to the [`showcase/vue` host](../../showcase/vue/).
+Feature coverage and catalog ownership belong to
+[`showcase/shared/frontend-registry.json`](../../showcase/shared/frontend-registry.json)
+and the existing Showcase generation and validation workflows. Read
+[`showcase/AGENTS.md`](../../showcase/AGENTS.md) before changing a Showcase cell.
+The Vue Storybook under [`examples/v2/vue/storybook`](../../examples/v2/vue/storybook)
+is useful for component development, but is not the canonical integration or
+long-form documentation owner.
+
+## Nx validation
+
+Run package tasks through Nx:
+
+```bash
+pnpm nx run @copilotkit/vue:lint
+pnpm nx run @copilotkit/vue:check-types
+pnpm nx run @copilotkit/vue:test
+```
+
+Run the build when changing exports, bundling, CSS, declarations, or integration
+behavior:
+
+```bash
+pnpm nx run @copilotkit/vue:build
+```
+
+If the change includes the Vue Showcase host, use its current targets from the
+[host README](../../showcase/vue/README.md): `test`, `build`, and
+`consumer-check-types`. If it includes shell-docs, follow its
+[validation commands](../../showcase/shell-docs/README.md#validate-changes).

package/PARITY.md

@@ -5,21 +5,30 @@ Keep it updated whenever React parity work lands in `packages/vue`.
 
 ## Scope and source of truth
 
-- Scope: `packages/vue/**` only.
+- Primary implementation and parity-matrix scope: `packages/vue/**`. This file may point to executable Vue integration surfaces without duplicating their ownership data.
 - Canonical source: `packages/react-core/`, `packages/react-ui/`, `packages/react-textarea/`.
 - Goal: semantic parity plus high discoverability.
-- Current priority: package-only parity. Avoid upstream/shared changes outside the Vue package until the Vue port is ready to merge.
+- Current priority: package parity within the established Vue package, documentation, and Showcase integration boundaries. Avoid broad shared-policy changes.
 
 ## Package boundary and documentation placement
 
 - `@copilotkit/vue` follows the same single-package direction as `@copilotkit/react`.
 - Core hooks/providers/types and UI-facing rendering primitives should live in this package.
 - Keep scope aligned with React's package surface; avoid introducing a parallel `vue-ui` package split.
-- Do not add Vue-only hook/component pages to the shared `docs/` V2 reference unless the repository adopts an explicit Vue section there.
-- Keep user-facing package usage and API docs in `README.md`.
-- Keep user-facing visual docs/examples in `examples/v2/vue/storybook/**`.
+- Long-form user documentation and API reference belong in `showcase/shell-docs/`.
+- Keep `README.md` as the npm-facing package entry point for installation and concise usage.
+- Runnable visual examples belong to the Showcase Vue host and generated frontend catalogs; Storybook is not the canonical integration surface.
 - Keep parity policy, translation rules, checklist, and the living React-to-Vue matrix in this file.
-- Treat Storybook/demo parity as follow-up work outside this package unless the task explicitly enters a repo-wide parity phase.
+- Showcase coverage and build ownership live in `showcase/shared/frontend-registry.json`, the generated frontend catalogs, and the existing Showcase validation/build workflows. Link to those sources instead of duplicating cell counts, feature counts, or a second coverage table here.
+- Vue documentation governance: React root IA is canonical; Vue navigation is derived and filtered through frontend resolution; shared pages and Vue variants follow the established policy; automated tests, not a duplicated route table, verify parity.
+- Vue-local documentation exceptions preserve the shared AG-UI Streams, thread-import, and Inspector pages without changing other frontend policy, while keeping A2UI and detailed v1 material outside the accepted Vue surface.
+
+## Verification boundary
+
+- Package behavior is verified by the Vue package's Nx test, type-check, lint, and build targets as applicable.
+- Existing Showcase validation and build workflows provide automatic canonical-artifact, integration-image staging/build, and hosting-contract validation for relevant pull requests.
+- There is no full automatic Vue browser/runtime matrix on every pull request. Artifact and image-build success is not browser/runtime passing evidence.
+- Currently visible consumer type failures remain outside this passing evidence; this document does not suppress, allowlist, or redefine them.
 
 ## API compatibility policy
 
@@ -364,14 +373,14 @@ For package-level parity work, all items below are required before a ported Reac
 4. Code-level docs parity:
    New public hooks/composables include JSDoc on implementation with at least one usage example.
 5. Package docs parity:
-   User-facing Vue notes remain documented in `README.md`.
+   Concise npm-facing Vue notes remain documented in `README.md`; long-form user documentation and reference live in shell-docs.
 
-Out-of-package follow-up, when the repo enters repo-wide parity work:
+Executable integration follow-up for user-visible features:
 
 1. Visual parity:
-   Add or update the corresponding Vue Storybook story for user-visible features.
+   Add or update the corresponding runnable surface in the Showcase Vue host/catalog.
 2. Demo/example parity:
-   Add or update runnable Vue demo/example usage for user-visible features.
+   Update the Showcase-owned registry/catalog inputs without duplicating coverage data in this file.
 
 ## React -> Vue Parity Matrix
 

package/README.md

@@ -1,403 +1,54 @@
 # @copilotkit/vue
 
-Vue 3 bindings for CopilotKit2: providers, composables, and chat rendering primitives for integrating AI agents into Vue applications.
-
-## Documentation Location
-
-Vue-specific documentation does not belong in the shared `docs/` V2 reference unless the repository adds a dedicated Vue docs section there.
-
-- Keep package usage and API guidance in this README.
-- Keep parity policy, architectural translation decisions, strict test-port rules, and the living React-to-Vue matrix in [PARITY.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/PARITY.md).
-- Put public-facing Vue API and component documentation in Vue Storybook under `examples/v2/vue/storybook`.
-
-## Parity Delivery Checklist
-
-The parity checklist and strict translatability rules are maintained in [PARITY.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/PARITY.md). Use it as the source of truth for parity completion and for deciding when tests must mirror React literally.
-
-## Parity Workflow
-
-Follow [PARITY.md](https://github.com/CopilotKit/CopilotKit/blob/main/packages/vue/PARITY.md) for parity workflow. If a feature is not clearly near-100% translatable, discuss the API/test divergence before introducing a Vue-specific translation. Update the matrix in the same change when behavior or tests change.
+Vue 3 components and composables for connecting an app to CopilotKit Runtime and rendering agent chat UI. The package includes `CopilotKitProvider`, `CopilotChat`, `CopilotSidebar`, `CopilotPopup`, and composables for agents, tools, context, suggestions, threads, interrupts, and custom rendering.
 
 ## Installation
 
 ```bash
-pnpm add @copilotkit/vue @copilotkit/core
+npm install @copilotkit/vue
 ```
 
-Import package styles once in your app entry:
+The package requires Vue 3.3 or newer. Your app also needs a Copilot Runtime endpoint, such as `/api/copilotkit`. If you host the runtime yourself, install `@copilotkit/runtime` in the server project.
 
-```ts
-import "@copilotkit/vue/styles.css";
-```
-
-`styles.css` is generated from `src/styles/globals.css` via Tailwind (`pnpm -C packages/vue build:css`).
-The Vue package styles are self-contained and do not require importing `@copilotkit/react/styles.css`.
-
-## Basic Usage
+## Quick start
 
 ```vue
+<!-- App.vue -->
 <script setup lang="ts">
-import { CopilotKitProvider } from "@copilotkit/vue";
+import { CopilotChat, CopilotKitProvider } from "@copilotkit/vue/v2";
+import "@copilotkit/vue/styles.css";
 </script>
 
 <template>
   <CopilotKitProvider runtime-url="/api/copilotkit">
-    <slot />
-  </CopilotKitProvider>
-</template>
-```
-
-### Inspector
-
-The provider mounts the Inspector automatically in development. It is never
-loaded in production or during server rendering. Disable it when needed with
-`<CopilotKitProvider :enable-inspector="false">`. The deprecated
-`showDevConsole` prop does not control Inspector visibility.
-
-## Provider Parity: `selfManagedAgents`, `onError`, and `a2ui`
-
-`CopilotKitProvider` supports React-parity provider controls for local agent registration and runtime error handling.
-
-```vue
-<script setup lang="ts">
-import { CopilotKitProvider } from "@copilotkit/vue";
-import type { CopilotKitCoreErrorCode } from "@copilotkit/core";
-
-function onProviderError(event: {
-  error: Error;
-  code: CopilotKitCoreErrorCode;
-  context: Record<string, any>;
-}) {
-  console.error(
-    "CopilotKit provider error",
-    event.code,
-    event.context,
-    event.error,
-  );
-}
-</script>
-
-<template>
-  <CopilotKitProvider
-    runtime-url="/api/copilotkit"
-    :self-managed-agents="{}"
-    :on-error="onProviderError"
-    :a2ui="{ theme: { mode: 'light' } }"
-  >
-    <slot />
-  </CopilotKitProvider>
-</template>
-```
-
-Notes:
-
-- `selfManagedAgents` is merged with `agents__unsafe_dev_only`, with `selfManagedAgents` taking precedence for duplicate IDs.
-- `onError` receives provider-scope core errors and is independent from chat-level `CopilotChat.onError`.
-- `a2ui.theme` customizes the built-in `a2ui-surface` fallback renderer when the runtime reports `a2uiEnabled: true`.
-
-### Provider `debug` logging
-
-`CopilotKitProvider` accepts a `debug` prop that mirrors the React `debug` surface. It toggles client-side debug logging on the underlying core and is kept in sync at runtime as the prop changes.
-
-Supported values match React parity:
-
-- `true` / `false` — enables or disables event + lifecycle logging (verbose payloads stay off).
-- `{ events?: boolean; lifecycle?: boolean; verbose?: boolean }` — granular control; `verbose` opts into full event payloads.
-
-```vue
-<script setup lang="ts">
-import { CopilotKitProvider, type DebugConfig } from "@copilotkit/vue";
-
-const debug: DebugConfig = { events: true, lifecycle: true, verbose: false };
-</script>
-
-<template>
-  <CopilotKitProvider runtime-url="/api/copilotkit" :debug="debug">
-    <slot />
-  </CopilotKitProvider>
-</template>
-```
-
-Prop updates are forwarded to the stable `CopilotKitCoreVue` instance via `setDebug(...)`, so changing `debug` at runtime does not recreate the provider or the core instance.
-
-## Chat Error Parity: `CopilotChat.onError`
-
-`CopilotChat` also exposes an `onError` callback with React-parity filtering semantics.
-It only forwards errors for the resolved chat agent (or global errors without an `agentId`).
-
-```vue
-<script setup lang="ts">
-import { CopilotChat } from "@copilotkit/vue";
-
-function onChatError(event: {
-  error: Error;
-  code: string;
-  context: Record<string, any>;
-}) {
-  console.error("CopilotChat error", event.code, event.context, event.error);
-}
-</script>
-
-<template>
-  <CopilotChat agent-id="default" :on-error="onChatError" />
-</template>
-```
-
-Notes:
-
-- Provider `onError` and chat `onError` are independent subscriptions and can both fire for the same matching error.
-- Chat `onError` ignores errors scoped to other `agentId` values.
-
-## Chat Rendering (Slot-Based)
-
-`@copilotkit/vue` uses Vue named/scoped slots for message, activity, and tool rendering:
-
-- `CopilotChatMessageView`
-- `CopilotChatToolCallsView`
-- `CopilotChatInput`
-
-```vue
-<template>
-  <CopilotChatMessageView :messages="messages" :is-running="isRunning">
-    <template #message-before="{ message, runId, messageIndexInRun }">
-      <MessageMeta
-        :id="message.id"
-        :run-id="runId"
-        :index-in-run="messageIndexInRun"
-      />
-    </template>
-
-    <template #assistant-message="{ message }">
-      <AssistantBubble :content="message.content" />
-    </template>
-
-    <template #activity-mcp-apps="{ content }">
-      <MyMcpActivity :content="content" />
-    </template>
-
-    <template #tool-call-search_docs="{ args, status, result }">
-      <SearchDocsToolCall :args="args" :status="status" :result="result" />
-    </template>
-
-    <template #tool-call="{ name, args, status }">
-      <GenericToolCall :name="name" :args="args" :status="status" />
-    </template>
-  </CopilotChatMessageView>
-</template>
-```
-
-Supported message-level slots:
-
-- `message-before`
-- `assistant-message`
-- `user-message`
-- `reasoning-message`
-- `activity-<activityType>` (dynamic)
-- `activity-message` (fallback)
-- `message-after`
-- `cursor`
-
-Supported tool-level slots:
-
-- `tool-call-<toolName>` (dynamic)
-- `tool-call` (fallback)
-
-## Programmatic Custom Message Registration
-
-Slots remain the primary Vue customization path for chat/message rendering. When you need reusable shared renderers with provider-managed ordering or agent scoping, `CopilotKitProvider` also accepts `render-custom-messages` as a secondary API.
-
-```vue
-<script setup lang="ts">
-import { CopilotKitProvider, CopilotChat } from "@copilotkit/vue";
-import { defineComponent } from "vue";
-
-const AuditBadge = defineComponent({
-  props: {
-    message: { type: Object, required: true },
-    position: { type: String, required: true },
-  },
-  template: `
-    <div
-      v-if="position === 'after' && message.role === 'assistant'"
-      :data-testid="'audit-' + message.id"
-    >
-      Audited
-    </div>
-  `,
-});
-
-const renderCustomMessages = [
-  { render: AuditBadge },
-  { agentId: "sales-agent", render: AuditBadge },
-];
-</script>
-
-<template>
-  <CopilotKitProvider
-    runtime-url="/api/copilotkit"
-    :render-custom-messages="renderCustomMessages"
-  >
-    <CopilotChat agent-id="sales-agent" />
+    <main style="height: 100dvh">
+      <CopilotChat />
+    </main>
   </CopilotKitProvider>
 </template>
 ```
 
-Use:
-
-- `#message-before` / `#message-after` for local template-level customization in a specific chat or message view
-- provider `render-custom-messages` for reusable renderer registration, ordered evaluation, and agent-scoped overrides
-
-## Reasoning Messages
-
-`CopilotChatMessageView` supports reasoning messages via the `reasoning-message` slot, with a default `CopilotChatReasoningMessage` fallback.
-
-Default reasoning behavior mirrors React semantics:
+Import `@copilotkit/vue/styles.css` once in your app. `CopilotChat` uses the provider's default agent when `agent-id` is omitted. The chat fills its parent, so give that container a height.
 
-- Shows `Thinking…` while the reasoning message is the latest streaming message.
-- Switches to `Thought for ...` when reasoning finishes.
-- Auto-opens while streaming and auto-collapses on completion.
-- Hides the chat-level cursor when the latest message is reasoning.
+## Imports and compatibility
 
-## Current Scope
-
-- **Providers**: `CopilotKitProvider`, `CopilotChatConfigurationProvider`
-- **Composables**: `useCopilotKit`, `useCopilotChatConfiguration`, `useAgent`, `useAgentContext`, `useFrontendTool`, `useRenderTool`, `useDefaultRenderTool`, `useComponent`, `useHumanInTheLoop`, `useSuggestions`, `useConfigureSuggestions`, `useThreads`, `useInterrupt`
-- **Components**: `CopilotChat`, `CopilotKitInspector`, `CopilotChatAssistantMessage`, `CopilotChatUserMessage`, `CopilotChatReasoningMessage`, `CopilotChatMessageView`, `CopilotChatSuggestionPill`, `CopilotChatSuggestionView`, `CopilotChatInput`, `CopilotChatToggleButton`, `CopilotModalHeader`, `CopilotChatView`, `CopilotChatToolCallsView`, `CopilotSidebarView`, `CopilotPopupView`, `CopilotSidebar`, `CopilotPopup`, `MCPAppsActivityRenderer`, `A2UISurfaceActivityRenderer`
-- **Markdown Renderer**: `CopilotChatAssistantMessage` uses `streamdown-vue` (with KaTeX support)
-- **Core**: `CopilotKitCoreVue`
-
-## Threads
-
-```vue
-<script setup lang="ts">
-import { useThreads } from "@copilotkit/vue";
-
-const {
-  threads,
-  isLoading,
-  hasMoreThreads,
-  isFetchingMoreThreads,
-  fetchMoreThreads,
-  renameThread,
-  deleteThread,
-} = useThreads({
-  agentId: "agent-1",
-  includeArchived: false,
-  limit: 20,
-});
-
-function loadMoreThreads() {
-  if (hasMoreThreads.value && !isFetchingMoreThreads.value) {
-    fetchMoreThreads();
-  }
-}
-</script>
-
-<template>
-  <div v-if="isLoading">Loading…</div>
-  <ul v-else>
-    <li v-for="thread in threads" :key="thread.id">
-      {{ thread.name ?? "Untitled" }}
-      <button @click="renameThread(thread.id, 'Renamed')">Rename</button>
-      <button @click="deleteThread(thread.id)">Delete</button>
-    </li>
-  </ul>
-  <button
-    v-if="hasMoreThreads"
-    :disabled="isFetchingMoreThreads"
-    @click="loadMoreThreads"
-  >
-    {{ isFetchingMoreThreads ? "Loading..." : "Load more" }}
-  </button>
-</template>
-```
-
-`useThreads` is a headless composable for CopilotKit Intelligence thread lists scoped to the runtime-authenticated user and provided `agentId`. It supports optional `includeArchived` and `limit` inputs, subscribes to realtime metadata updates when the runtime exposes a websocket URL, and returns reactive refs for `threads`, `isLoading`, `error`, `hasMoreThreads`, and `isFetchingMoreThreads`, plus `fetchMoreThreads()`.
-
-### `useInterrupt`
-
-`useInterrupt` handles agent `on_interrupt` events without requiring Vue users to write render functions or TSX.
-
-For in-chat usage, combine the composable with the `#interrupt` slot on `CopilotChat`:
-
-```vue
-<script setup lang="ts">
-import { useInterrupt } from "@copilotkit/vue";
-
-useInterrupt({
-  handler: async ({ event }) => ({ label: String(event.value) }),
-});
-</script>
-
-<template>
-  <CopilotChat>
-    <template #interrupt="{ event, result, resolve }">
-      <button @click="resolve({ approved: true, value: event.value })">
-        {{ result?.label ?? event.value }}
-      </button>
-    </template>
-  </CopilotChat>
-</template>
-```
-
-For manual placement, use `renderInChat: false` and consume the returned refs:
+Use the `/v2` subpath for new code:
 
 ```ts
-const { interrupt, result, hasInterrupt, resolveInterrupt } = useInterrupt({
-  renderInChat: false,
-});
-```
-
-## Icon Foundation (Internal)
-
-- Chat/UI components should import icons from `src/components/icons/index.ts`.
-- Do not import from `lucide-vue-next` directly in Vue package components.
-- This adapter is internal and intentionally not exported from the package root.
-
-## Text Input
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
 import {
-  CopilotChatConfigurationProvider,
-  CopilotChatInput,
-} from "@copilotkit/vue";
-
-const input = ref("");
-
-function onSubmitMessage(value: string) {
-  console.log("submit:", value);
-}
-</script>
-
-<template>
-  <CopilotChatConfigurationProvider thread-id="thread-1" agent-id="default">
-    <CopilotChatInput
-      v-model="input"
-      :tools-menu="[
-        { label: 'Insert template', action: () => console.log('template') },
-      ]"
-      @submit-message="onSubmitMessage"
-      @add-file="() => {}"
-      @start-transcribe="() => {}"
-      @cancel-transcribe="() => {}"
-      @finish-transcribe="() => {}"
-    />
-  </CopilotChatConfigurationProvider>
-</template>
+  CopilotChat,
+  CopilotKitProvider,
+  useFrontendTool,
+} from "@copilotkit/vue/v2";
 ```
 
-Key parity props:
+The root import, `@copilotkit/vue`, re-exports the v2 API and keeps compatibility wrappers for `CopilotKit`, `useCopilotAction`, `useFrontendTool`, and `useCopilotReadable`. The legacy tool wrappers accept `Parameter[]` definitions. Use `/v2` for the current Standard Schema tool APIs, including Zod, Valibot, and ArkType schemas.
+
+In Vue templates, camelCase props become kebab-case attributes. For example, `runtimeUrl` is written as `runtime-url`, and boolean or object props use `:` bindings such as `:enable-inspector="false"`. Vue rendering customization uses named and scoped slots where React uses render props.
 
-- `mode`: `"input" | "transcribe" | "processing"`
-- `toolsMenu`: nested menu items + separators (`"-"`)
-- `positioning`: `"static" | "absolute"`
-- `keyboardHeight`: number (mobile keyboard offset)
-- `showDisclaimer`: explicit override, otherwise defaults by positioning
+## Documentation
 
-Key slots:
+- [Vue getting started guide](https://docs.copilotkit.ai/vue)
+- [Vue API reference](https://docs.copilotkit.ai/reference/vue)
 
-- `text-area`, `send-button`, `add-menu-button`
-- `start-transcribe-button`, `cancel-transcribe-button`, `finish-transcribe-button`
-- `audio-recorder`, `disclaimer`, `layout`
+The full Vue docs cover runtime setup, prebuilt chat components, composables, tools, threads, interrupts, attachments, voice, and customization.