experimental-ash 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # experimental-ash
 
+## 0.64.0
+
+### Minor Changes
+
+- 76d7a1f: Add `placeholderAuth()` for scaffolded Web Chat channels so production requests return a structured 401 when app auth has not been configured. Generated apps now show setup guidance instead of an internal channel failure, and `ClientError` surfaces structured Ash error messages directly.
+
+### Patch Changes
+
+- 030c0d1: Fix Slack direct messages dropping file uploads. `onDirectMessage` now receives `file_share` messages with their attachments intact, matching the existing `onAppMention` behavior; system subtypes (edits, deletes, joins) and bot-authored echoes are still filtered.
+
+## 0.63.0
+
+### Minor Changes
+
+- 524cae7: Add `createWebSocketUpgradeServer()` as an escape hatch for `WS()` routes that need to adapt SDKs or frameworks which bind directly to Node `http.Server` upgrade events.
+- a491826: Add Svelte 5 and SvelteKit integrations, including a `useAshAgent` binding, a SvelteKit Vite plugin for Ash route proxying, Vercel services configuration, docs, tests, and an example app.
+- a491826: Add Vue composable (`useAshAgent`) and Nuxt module (`experimental-ash/nuxt`) for building agent UIs with Vue and Nuxt. The shared `AshAgentStore` class is now exported from `experimental-ash/client` for framework-agnostic consumption.
+
+## 0.62.1
+
+### Patch Changes
+
+- d141e9e: Update `@workflow/*` dependencies to the latest beta: `@workflow/core` 5.0.0-beta.12, `@workflow/errors` 5.0.0-beta.7, `@workflow/world` 5.0.0-beta.7, and `@workflow/world-local` 5.0.0-beta.13.
+
 ## 0.62.0
 
 ### Minor Changes

package/dist/docs/public/advanced/auth-and-route-protection.mdx

@@ -18,13 +18,13 @@ These settings apply to:
 - `POST /ash/v1/session/:sessionId`
 - `GET /ash/v1/session/:sessionId/stream`
 
-<CopyPrompt text="Protect the user's Ash HTTP routes through the channel layer. In Ash, route auth and IP policy live on channel factories, usually agent/channels/ash.ts with ashChannel auth config, not in agent.ts. Inspect the existing channel file and app auth code, replace any generated exampleProductionAuth placeholder with the smallest AuthFn or helper composition, use helpers such as localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets in environment variables, preserve localDev and vercelOidc behavior where useful, verify unauthenticated production browser requests are rejected with 401, and do not commit unless the user asks.">
+<CopyPrompt text="Protect the user's Ash HTTP routes through the channel layer. In Ash, route auth and IP policy live on channel factories, usually agent/channels/ash.ts with ashChannel auth config, not in agent.ts. Inspect the existing channel file and app auth code, replace any generated placeholderAuth guardrail with the smallest AuthFn or helper composition, use helpers such as localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets in environment variables, preserve localDev and vercelOidc behavior where useful, verify unauthenticated production browser requests are rejected with 401, and do not commit unless the user asks.">
   Protect the user's Ash HTTP routes through the channel layer. In Ash, route auth and IP policy
   live on channel factories, usually agent/channels/ash.ts with ashChannel auth config, not in
   agent.ts. Inspect the existing channel file and app auth code, replace any generated
-  exampleProductionAuth placeholder with the smallest AuthFn or helper composition, use helpers such
-  as localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets
-  in environment variables, preserve localDev and vercelOidc behavior where useful, verify
+  placeholderAuth guardrail with the smallest AuthFn or helper composition, use helpers such as
+  localDev, vercelOidc, none, httpBasic, jwtHmac, jwtEcdsa, or oidc as appropriate, keep secrets in
+  environment variables, preserve localDev and vercelOidc behavior where useful, verify
   unauthenticated production browser requests are rejected with 401, and do not commit unless the
   user asks.
 </CopyPrompt>
@@ -32,31 +32,24 @@ These settings apply to:
 ## Generated Web Chat Auth
 
 `pnpm create experimental-ash-agent` scaffolds `agent/channels/ash.ts` from the Web Chat example.
-Creating this file overrides the default Ash channel settings. The generated version permits Vercel
-OIDC and localhost requests and leaves end-user production auth as an explicit placeholder:
+It permits Vercel OIDC and localhost requests, but it will not allow browser requests in
+production until you replace the placeholder with your app's auth:
 
 ```ts
 // agent/channels/ash.ts
 import { ashChannel } from "experimental-ash/channels/ash";
-import { type AuthFn, localDev, vercelOidc } from "experimental-ash/channels/auth";
-
-function exampleProductionAuth(): AuthFn<Request> {
-  return () => {
-    if (process.env.VERCEL_ENV === "production") {
-      throw new Error("Configure production auth in agent/channels/ash.ts.");
-    }
-    return null;
-  };
-}
+import { localDev, placeholderAuth, vercelOidc } from "experimental-ash/channels/auth";
 
 export default ashChannel({
-  auth: [vercelOidc(), localDev(), exampleProductionAuth()],
+  auth: [localDev(), vercelOidc(), placeholderAuth()],
 });
 ```
 
-Replace `exampleProductionAuth()` before a browser user submits a production request. If you
-delete the authored file, Ash falls back to its framework default `[localDev(), vercelOidc()]`;
-that default also does not accept browser-user traffic in production.
+Replace `placeholderAuth()` before a browser user submits a production request. It returns a
+structured 401 in production so generated Web Chat apps can explain that auth is not configured
+instead of showing an internal channel error. If you delete the authored file, Ash falls back to
+its framework default `[localDev(), vercelOidc()]`; that default also does not accept browser
+traffic in production.
 
 ## Walking The Auth Array
 
@@ -68,6 +61,19 @@ that default also does not accept browser-user traffic in production.
 If every entry skips, the request is rejected with `401`. An empty array `auth: []` therefore
 rejects every request.
 
+To reject with a specific `401`, throw an `UnauthenticatedError`. To reject with a specific `403`,
+throw a `ForbiddenError`. `routeAuth` turns those errors into HTTP responses; other thrown errors
+still use the normal channel failure path.
+
+```ts
+import { UnauthenticatedError } from "experimental-ash/channels/auth";
+
+throw new UnauthenticatedError({
+  code: "authentication_required",
+  message: "Sign in to continue.",
+});
+```
+
 To accept anonymous traffic, include `none()` as the final entry:
 
 ```ts

package/dist/docs/public/advanced/hooks.mdx

@@ -6,8 +6,10 @@ url: /hooks
 
 Hooks are Ash's authored extension points for the runtime event stream.
 
-This page is about `agent/hooks/*.ts` runtime hooks. For the React client hook,
-see [`useAshAgent`](../frontend/use-ash-agent.md).
+This page is about `agent/hooks/*.ts` runtime hooks. For the client-side hook,
+see [`useAshAgent`](../frontend/use-ash-agent.md) (React) or
+[`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md) or
+[`useAshAgent` (Svelte)](../frontend/use-ash-agent-svelte.md).
 
 Use a hook when you want to observe stream events (audit, metrics,
 alerting) without writing a tool, a context provider, or a channel
@@ -188,7 +190,11 @@ when both are registered.
 ## What to read next
 
 - [`useAshAgent`](../frontend/use-ash-agent.md)
+- [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
+- [`useAshAgent` (Svelte)](../frontend/use-ash-agent-svelte.md)
 - [Next.js](../frontend/nextjs.md)
+- [Nuxt](../frontend/nuxt.md)
+- [SvelteKit](../frontend/sveltekit.md)
 - [Tools](./tools.mdx)
 - [Context Control](./context-control.md)
 - [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/advanced/runs-and-streaming.md

@@ -13,9 +13,10 @@ The key client model is:
 - `POST /ash/v1/session/:sessionId` sends a follow-up message
 - `GET /ash/v1/session/:sessionId/stream` lets you watch the session in real time
 
-React apps can use [`useAshAgent()`](../frontend/use-ash-agent.md) instead of calling these
-routes directly. Next.js apps can use [`withAsh()`](../frontend/nextjs.md) to proxy these
-routes to the Ash runtime from the same origin.
+React apps can use [`useAshAgent()`](../frontend/use-ash-agent.md) and Vue apps can use
+[`useAshAgent()` (Vue)](../frontend/use-ash-agent-vue.md) instead of calling these routes
+directly. [Next.js](../frontend/nextjs.md) and [Nuxt](../frontend/nuxt.md) apps can proxy
+these routes to the Ash runtime from the same origin.
 
 Ash keeps those separate on purpose:
 
@@ -127,7 +128,9 @@ channel has already updated its state and the projection is current.
 ## What To Read Next
 
 - [`useAshAgent`](../frontend/use-ash-agent.md)
+- [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
 - [Next.js](../frontend/nextjs.md)
+- [Nuxt](../frontend/nuxt.md)
 - [Session Context](./session-context.md)
 - [Subagents](./subagents.mdx)
 - [Schedules](./schedules.mdx)

package/dist/docs/public/advanced/typescript-api.md

@@ -18,6 +18,10 @@ Source of truth:
 - React subpath: [`../../packages/ash/src/react/index.ts`](../../packages/ash/src/react/index.ts)
 - client subpath: [`../../packages/ash/src/client/index.ts`](../../packages/ash/src/client/index.ts)
 - evals subpath: [`../../packages/ash/src/evals/index.ts`](../../packages/ash/src/evals/index.ts)
+- vue subpath: [`../../packages/ash/src/vue/index.ts`](../../packages/ash/src/vue/index.ts)
+- nuxt subpath: [`../../packages/ash/src/public/nuxt/index.ts`](../../packages/ash/src/public/nuxt/index.ts)
+- svelte subpath: [`../../packages/ash/src/svelte/index.ts`](../../packages/ash/src/svelte/index.ts)
+- SvelteKit subpath: [`../../packages/ash/src/public/sveltekit/index.ts`](../../packages/ash/src/public/sveltekit/index.ts)
 
 ## Definition Helpers
 
@@ -85,6 +89,32 @@ React helpers exported from `experimental-ash/react`:
 - `UseAshAgentOptions`, `UseAshAgentHelpers`, `UseAshAgentSnapshot`, `UseAshAgentStatus` - hook configuration and state types
 - `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - default message projection types
 
+Nuxt helpers exported from `experimental-ash/nuxt`:
+
+- `default` - the Nuxt module that runs the Ash agent alongside your Nuxt app
+- `ASH_NUXT_SERVICE_PREFIX` - default private Vercel service prefix for the Ash service
+- `AshNuxtModuleOptions` - options for `ashRoot`, `ashBuildCommand`, `configureVercelJson`, and `servicePrefix`
+
+Vue helpers exported from `experimental-ash/vue`:
+
+- `useAshAgent(options?)` - Vue composable for sending turns, streaming events, projecting reactive UI state, and tracking a session cursor
+- `defaultMessageReducer()` - default chat-style event projection used by `useAshAgent()`
+- `UseAshAgentOptions`, `UseAshAgentReturn`, `UseAshAgentSnapshot`, `UseAshAgentStatus`, `PrepareSend` - composable configuration and state types
+- `AshAgentReducer`, `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - reducer and default message projection types
+
+SvelteKit helpers exported from `experimental-ash/sveltekit`:
+
+- `ashSvelteKit(options?)` - Vite plugin that runs the Ash agent alongside your SvelteKit app
+- `ASH_SVELTEKIT_SERVICE_PREFIX` - default private Vercel service prefix for the Ash service
+- `AshSvelteKitPluginOptions` - options for `ashRoot`, `ashBuildCommand`, `configureVercelJson`, and `servicePrefix`
+
+Svelte helpers exported from `experimental-ash/svelte`:
+
+- `useAshAgent(options?)` - Svelte 5 binding for sending turns, streaming events, projecting rune-friendly UI state, and tracking a session cursor
+- `defaultMessageReducer()` - default chat-style event projection used by `useAshAgent()`
+- `UseAshAgentOptions`, `UseAshAgentReturn`, `UseAshAgentSnapshot`, `UseAshAgentStatus`, `PrepareSend` - binding configuration and state types
+- `AshAgentReducer`, `AshMessageData`, `AshMessage`, `AshMessagePart`, `AshDynamicToolPart` - reducer and default message projection types
+
 Client helpers exported from `experimental-ash/client`:
 
 - `Client` - HTTP client for an Ash server
@@ -321,6 +351,8 @@ import { Braintrust } from "experimental-ash/evals/reporters";
 - `ctx.session` -> [Session Context](./session-context.md)
 - `withAsh` -> [Next.js](../frontend/nextjs.md)
 - `useAshAgent` -> [`useAshAgent`](../frontend/use-ash-agent.md)
+- `useAshAgent` (Vue) and `defaultMessageReducer` -> [`useAshAgent` (Vue)](../frontend/use-ash-agent-vue.md)
+- Nuxt module (`experimental-ash/nuxt`) -> [Nuxt](../frontend/nuxt.md)
 - subagents (authored with `defineAgent` under `subagents/<id>/agent.ts`) -> [Subagents](./subagents.mdx)
 - `defineSchedule` -> [Schedules](./schedules.mdx)
 - `defineEvalSuite`, loaders, reporters, and scorers -> [Evals](./evals.mdx)

package/dist/docs/public/channels/ash.mdx

@@ -58,7 +58,11 @@ wire the Ash channel to your app's auth system, such as Clerk, Auth.js, or your
 verification.
 
 `pnpm create experimental-ash-agent` scaffolds an example `agent/channels/ash.ts` with a production
-auth placeholder so you can replace it before exposing the API to real users.
+auth placeholder so you can replace it before exposing the API to real users. The generated channel
+permits Vercel OIDC and localhost requests and includes `placeholderAuth()`, which returns a
+setup-focused 401 in production until you replace it with your app's auth. If you delete the
+authored file, Ash falls back to `[localDev(), vercelOidc()]`; that default does not admit browser
+users in production.
 
 For the full auth model and helper list, see
 [Auth and Route Protection](/docs/auth-and-route-protection).

package/dist/docs/public/channels/custom.mdx

@@ -89,6 +89,29 @@ export default defineChannel({
 `params`, `waitUntil`, and `requestIp`. The returned hooks are Ash-owned structural types compatible
 with Nitro/H3 websocket routing, including `upgrade`, `open`, `message`, `close`, and `error`.
 
+### Node upgrade server escape hatch
+
+Prefer the `WS()` lifecycle hooks above when you own the websocket behavior. Ash also exposes
+`createWebSocketUpgradeServer()` for the narrower case where a third-party SDK or framework expects
+to bind directly to a Node `http.Server` with `server.on("upgrade", ...)`.
+
+```ts
+import { defineChannel, WS, createWebSocketUpgradeServer } from "experimental-ash/channels";
+
+const bridge = createWebSocketUpgradeServer();
+
+thirdPartySdk.attach(bridge.server);
+
+export default defineChannel({
+  routes: [WS("/vendor/ws", bridge.route)],
+});
+```
+
+The bridge server does not listen on its own port. It receives only upgrade events that matched the
+Ash route, and only on hosts where Nitro exposes the raw Node upgrade request, socket, and head. Treat
+it as a compatibility adapter for libraries with server-binding APIs, not as the primary way to build
+websocket channels in Ash.
+
 ## Cross-channel hand-off
 
 Route handlers can start a session on a different channel via `args.receive(channel, ...)`. Use this

package/dist/docs/public/frontend/README.md

@@ -4,13 +4,17 @@ description: "Wire your web app to an Ash agent."
 url: /frontend
 ---
 
-Ash ships first-class helpers for the two most common ways to put an agent
+Ash ships first-class helpers for the most common ways to put an agent
 behind a web UI:
 
 - [Next.js](./nextjs.md) — `withAsh()` runs the Ash agent alongside your
   Next.js app.
-- [`useAshAgent`](./use-ash-agent.md) — React hook for chat and agent UIs in any
-  React app.
+- [Nuxt](./nuxt.md) — `experimental-ash/nuxt` module runs the Ash agent
+  alongside your Nuxt app.
+- [`useAshAgent` (React)](./use-ash-agent.md) — React hook for chat and agent
+  UIs in any React app.
+- [`useAshAgent` (Vue)](./use-ash-agent-vue.md) — Vue composable for chat and
+  agent UIs in any Vue app.
 
 For other stacks, call Ash directly over its HTTP routes —
-see [Sessions And Streaming](../runs-and-streaming.md).
+see [Sessions And Streaming](../advanced/runs-and-streaming.md).

package/dist/docs/public/frontend/meta.json

@@ -1,3 +1,11 @@
 {
-  "pages": ["README", "nextjs", "use-ash-agent"]
+  "pages": [
+    "README",
+    "nextjs",
+    "nuxt",
+    "sveltekit",
+    "use-ash-agent",
+    "use-ash-agent-vue",
+    "use-ash-agent-svelte"
+  ]
 }

package/dist/docs/public/frontend/nextjs.md

@@ -198,11 +198,11 @@ next call only). See [`useAshAgent`](./use-ash-agent.md#add-per-turn-client-cont
 for the full pattern.
 
 For server-side enrichment (policy, durable context, dynamic skills), use
-runtime lifecycle hooks instead. See [Hooks](../hooks.md).
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
 
 ## What To Read Next
 
 - [`useAshAgent`](./use-ash-agent.md)
-- [Auth And Route Protection](../auth-and-route-protection.md)
-- [Hooks](../hooks.md)
-- [Sessions And Streaming](../runs-and-streaming.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)

package/dist/docs/public/frontend/nuxt.md

@@ -0,0 +1,168 @@
+---
+title: "Nuxt"
+description: "Add an Ash agent to a Nuxt app and call it from the browser."
+---
+
+`experimental-ash/nuxt` lets you ship a Nuxt frontend and an Ash agent as
+one project. Come in from either side: drop it into an existing Nuxt app
+to add an agent, or start with an agent and point a Nuxt project at it.
+
+- **One dev server.** `nuxt dev` runs the app and the agent together.
+- **One deploy.** Vercel ships them as a single project; no extra service to operate.
+- **Zero URL plumbing.** `useAshAgent()` finds the mounted routes automatically; no CORS, no env vars.
+
+## Add Ash To Nuxt
+
+Register the module in your Nuxt config:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+});
+```
+
+By default, the module looks for an `agent/` folder inside your Nuxt
+project root. Pass `ashRoot` when the agent lives somewhere else:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+  ash: {
+    ashRoot: "../my-agent",
+  },
+});
+```
+
+## Add The Ash Channel
+
+Skip this section if the framework default channel works for you. The module
+already wires Ash up without it.
+
+Create `agent/channels/ash.ts` when you want to choose the route auth policy
+explicitly:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { none } from "experimental-ash/channels/auth";
+
+export default ashChannel({
+  auth: none(),
+});
+```
+
+For protected apps, replace `none()` with a channel auth helper such as
+`vercelOidc()`, `oidc(...)`, or `httpBasic(...)`.
+
+## Use The Vue Composable
+
+Once the module is in `nuxt.config.ts`, browser code can use
+[`useAshAgent()`](./use-ash-agent-vue.md) without a custom host. The module
+auto-imports the composable, so no explicit import is needed:
+
+```vue
+<script setup lang="ts">
+const { status, sendMessage } = useAshAgent();
+
+const isBusy = computed(() => status.value === "submitted" || status.value === "streaming");
+
+const message = ref("");
+
+async function handleSubmit() {
+  const text = message.value.trim();
+  if (!text || isBusy.value) return;
+  message.value = "";
+  await sendMessage(text);
+}
+</script>
+
+<template>
+  <form @submit.prevent="handleSubmit">
+    <input v-model="message" :disabled="isBusy" />
+    <button type="submit" :disabled="isBusy">Send</button>
+  </form>
+</template>
+```
+
+The composable handles conversation state, streaming updates, errors, and
+messages for you. See [`useAshAgent` (Vue)](./use-ash-agent-vue.md) for the
+full API.
+
+## Local Development
+
+`pnpm dev` is enough. The module boots the Ash dev server alongside Nuxt
+and proxies the Ash routes to it, so your browser keeps talking to the
+Nuxt origin.
+
+## Vercel Deployments
+
+On Vercel, the module keeps the web app public and the Ash runtime tucked
+behind it. Users visit the Nuxt app, and the browser talks to the agent
+through the same site origin.
+
+Use `ashBuildCommand` when the agent needs a project-specific build command:
+
+```ts
+export default defineNuxtConfig({
+  modules: ["experimental-ash/nuxt"],
+  ash: {
+    ashBuildCommand: "pnpm build:ash",
+  },
+});
+```
+
+## Non-Vercel Production Hosts
+
+If you deploy somewhere other than Vercel and the Ash service runs on a
+separate origin, point Nuxt at it with `ASH_NUXT_PRODUCTION_ORIGIN`:
+
+```bash
+ASH_NUXT_PRODUCTION_ORIGIN=https://agent.example.com pnpm build
+```
+
+Set `ASH_NUXT_PRODUCTION_PORT` to use a different local port (default `4274`):
+
+```bash
+ASH_NUXT_PRODUCTION_PORT=5000 pnpm build && pnpm preview
+```
+
+## Authenticated Requests
+
+Because the agent runs on the same origin as your Nuxt app, the auth you
+already use for the rest of the app applies to it for free. Cookie-based
+sessions work without extra wiring: the browser already sends those cookies
+on every Ash request.
+
+For non-cookie schemes (bearer tokens, custom headers), attach them from the
+client instead:
+
+```vue
+<script setup lang="ts">
+const agent = useAshAgent({
+  headers: async () => ({
+    authorization: `Bearer ${await getAccessToken()}`,
+  }),
+});
+</script>
+```
+
+Prefer function values for short-lived credentials. Ash re-resolves them
+before each HTTP request, including reconnects.
+
+## Add Per-Turn Page Context
+
+`useAshAgent()` accepts a `prepareSend` callback for attaching one-turn page
+state (pathname, selected ids, anything else the model should see for the
+next call only). See [`useAshAgent` (Vue)](./use-ash-agent-vue.md#add-per-turn-client-context)
+for the full pattern.
+
+For server-side enrichment (policy, durable context, dynamic skills), use
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
+
+## What To Read Next
+
+- [`useAshAgent` (Vue)](./use-ash-agent-vue.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)

package/dist/docs/public/frontend/sveltekit.md

@@ -0,0 +1,177 @@
+---
+title: "SvelteKit"
+description: "Add an Ash agent to a SvelteKit app and call it from the browser."
+---
+
+`experimental-ash/sveltekit` lets you ship a SvelteKit frontend and an Ash
+agent as one project. Add the Vite plugin to an existing SvelteKit app, or
+start with an agent and point a SvelteKit project at it.
+
+- **One dev server.** `vite dev` runs the app and the agent together.
+- **One deploy.** Vercel ships them as a single project; no extra service to operate.
+- **Zero URL plumbing.** `useAshAgent()` finds the mounted routes automatically; no CORS, no env vars.
+
+## Add Ash To SvelteKit
+
+Register the plugin in your Vite config:
+
+```ts
+// vite.config.ts
+import { sveltekit } from "@sveltejs/kit/vite";
+import { ashSvelteKit } from "experimental-ash/sveltekit";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [ashSvelteKit(), sveltekit()],
+});
+```
+
+By default, the plugin looks for an `agent/` folder inside your SvelteKit
+project root. Pass `ashRoot` when the agent lives somewhere else:
+
+```ts
+export default defineConfig({
+  plugins: [
+    ashSvelteKit({
+      ashRoot: "../my-agent",
+    }),
+    sveltekit(),
+  ],
+});
+```
+
+## Add The Ash Channel
+
+Skip this section if the framework default channel works for you. The plugin
+already wires Ash up without it.
+
+Create `agent/channels/ash.ts` when you want to choose the route auth policy
+explicitly:
+
+```ts
+// agent/channels/ash.ts
+import { ashChannel } from "experimental-ash/channels/ash";
+import { none } from "experimental-ash/channels/auth";
+
+export default ashChannel({
+  auth: none(),
+});
+```
+
+For protected apps, replace `none()` with a channel auth helper such as
+`vercelOidc()`, `oidc(...)`, or `httpBasic(...)`.
+
+## Use The Svelte Binding
+
+Once the plugin is in `vite.config.ts`, browser code can use
+[`useAshAgent()`](./use-ash-agent-svelte.md) without a custom host:
+
+```svelte
+<script lang="ts">
+  import { useAshAgent } from "experimental-ash/svelte";
+
+  const agent = useAshAgent();
+  let message = $state("");
+  let isBusy = $derived(agent.status === "submitted" || agent.status === "streaming");
+
+  async function handleSubmit() {
+    const text = message.trim();
+    if (!text || isBusy) return;
+    message = "";
+    await agent.sendMessage(text);
+  }
+</script>
+
+<form onsubmit={(event) => {
+  event.preventDefault();
+  void handleSubmit();
+}}>
+  <input bind:value={message} disabled={isBusy} />
+  <button type="submit" disabled={isBusy}>Send</button>
+</form>
+```
+
+The binding handles conversation state, streaming updates, errors, and messages
+for you. See [`useAshAgent` (Svelte)](./use-ash-agent-svelte.md) for the full
+API.
+
+## Local Development
+
+`pnpm dev` is enough. The plugin boots the Ash dev server alongside SvelteKit
+and proxies the Ash routes to it, so your browser keeps talking to the
+SvelteKit origin.
+
+`pnpm build && pnpm preview` works the same way for local production preview:
+the preview server gets its own Ash route proxy and reuses or starts the shared
+Ash server automatically.
+
+## Vercel Deployments
+
+On Vercel, the plugin keeps the web app public and the Ash runtime tucked
+behind it. Users visit the SvelteKit app, and the browser talks to the agent
+through the same site origin.
+
+Use `ashBuildCommand` when the agent needs a project-specific build command:
+
+```ts
+export default defineConfig({
+  plugins: [
+    ashSvelteKit({
+      ashBuildCommand: "pnpm build:ash",
+    }),
+    sveltekit(),
+  ],
+});
+```
+
+## Non-Vercel Production Hosts
+
+If you deploy somewhere other than Vercel and the Ash service runs on a
+separate origin, pass `host` directly to `useAshAgent`:
+
+```ts
+const agent = useAshAgent({
+  host: "https://agent.example.com",
+});
+```
+
+## Authenticated Requests
+
+Because the agent runs on the same origin as your SvelteKit app, the auth you
+already use for the rest of the app applies to it for free. Cookie-based
+sessions work without extra wiring: the browser already sends those cookies on
+every Ash request.
+
+For non-cookie schemes (bearer tokens, custom headers), attach them from the
+client instead:
+
+```svelte
+<script lang="ts">
+  const agent = useAshAgent({
+    headers: async () => ({
+      authorization: `Bearer ${await getAccessToken()}`,
+    }),
+  });
+</script>
+```
+
+Prefer function values for short-lived credentials. Ash re-resolves them before
+each HTTP request, including reconnects.
+
+## Add Per-Turn Page Context
+
+`useAshAgent()` accepts a `prepareSend` callback for attaching one-turn page
+state (pathname, selected ids, anything else the model should see for the next
+call only). See
+[`useAshAgent` (Svelte)](./use-ash-agent-svelte.md#add-per-turn-client-context)
+for the full pattern.
+
+For server-side enrichment (policy, durable context, dynamic skills), use
+runtime lifecycle hooks instead. See [Hooks](../advanced/hooks.mdx).
+
+## What To Read Next
+
+- [`useAshAgent` (Svelte)](./use-ash-agent-svelte.md)
+- [Auth And Route Protection](../advanced/auth-and-route-protection.mdx)
+- [Hooks](../advanced/hooks.mdx)
+- [Sessions And Streaming](../advanced/runs-and-streaming.md)