@vanillaskyai/video 0.7.1 → 0.8.1

package/docs/architecture.md

@@ -24,11 +24,11 @@ validation, streaming, and player.
 | Location | Purpose |
 | --- | --- |
 | `src/server/create-video-chat-handler.ts` | Complete chat endpoint and capability boundary |
-| `src/server/create-video-handler.ts` | Lower-level video composition and provider adapter boundary |
+| `src/server/create-video-handler.ts` | Internal composition and provider adapter boundary |
 | `src/server/prompts/` | System and user prompts sent to the app-owned model |
 | `src/server/model/` | Converts provider text deltas into typed video plan parts |
 | `src/protocol/` | Shared request, event, validation, checksum, and SSE contract |
-| `src/player/` | Browser stream client, `useVideo`, timeline, and React player |
+| `src/player/` | Internal stream client, timeline, and React player |
 | `src/video-chat/` | Default `VideoChat` interface and headless conversation/session engine |
 | `src/visual-system/catalog/` | Template metadata, schemas, loading, and planner catalog |
 | `src/visual-system/scene-templates/` | Complete scenes the model may select |
@@ -36,7 +36,7 @@ validation, streaming, and player.
 | `src/visual-system/backgrounds/` | Standalone background renderers |
 | `src/visual-system/motion/` | Animation functions and timing behavior |
 | `src/visual-system/theme/` | Color and design tokens |
-| `src/cli/` | `vanillasky init` and `doctor`, plus `vanillasky templates create`, `add`, `sync`, `check`, `list`, and `describe` |
+| `src/cli/` | `vanillasky init`, `doctor`, and `providers add`, plus `vanillasky templates create`, `add`, `sync`, `check`, `list`, and `describe` |
 | `registry/items/` | Generated distributable copies installed into customer projects |
 | `src/index.ts`, `src/server.ts`, `src/react.ts`, `src/templates.ts`, `src/template-catalog.ts`, `src/test.ts`, `styles/video-chat.css` | The six small code entry points and one scoped stylesheet |
 
@@ -61,13 +61,13 @@ prompt/validation registry in `vanillasky/server.ts`.
 3. `createVideoChatHandler(...)` owns chat actions, suggestions, narration,
    capability discovery, and generated-video budgets. The application supplies
    provider callbacks and policy.
-4. Video answers flow into `createVideoHandler(...)`, which calls the
+4. Video answers flow into the internal composition pipeline, which calls the
    application's `streamText` adapter. This is where Anthropic, OpenAI, or
    another text model is connected.
 5. The system prompt combines the opening and composition rules with the trusted template
    catalog, including generated metadata for customer-owned templates. The user
-   prompt serializes the factual input, instructions,
-   personalization, brand, and approved media.
+   prompt serializes the prompt, completed conversation, instructions,
+   brand, and approved media.
 6. The model streams one host-consumed opening object followed by NDJSON plan
    parts. The server emits the opening event, then parses and validates complete
    scenes before emitting them.
@@ -75,8 +75,7 @@ prompt/validation registry in `vanillasky/server.ts`.
    loops or holds until its voice ends and the first playable scene is ready;
    the planned playback and narration then take over in one cut.
 
-The lower-level `useVideo` and `VideoPlayer` path skips chat actions and remains
-available for explicit one-shot video response integrations.
+`VideoPlayer` also replays completed chat videos parsed at the storage boundary.
 
 ## Where to change common behavior
 
@@ -93,7 +92,6 @@ available for explicit one-shot video response integrations.
 
 ## Public vocabulary
 
-Use `VideoChat`, `useVideoChat`, `createVideoChatHandler`, `Video`, `VideoInput`,
-`useVideo`, and `VideoPlayer` for the product API. Use “video response” when
+Use `VideoChat`, `useVideoChat`, `createVideoChatHandler`, `Video`, and `VideoPlayer` for the product API. Use “video response” when
 describing the lifecycle or output category. Use “motion” only for animation
 behavior inside the visual system.

package/docs/concepts.md

@@ -29,25 +29,13 @@ or export pipeline when an encoded file is required.
 
 ## Input
 
-`VideoInput` is the factual and creative boundary:
-
-- `input`: raw source material such as a roadmap update, launch brief, article,
-  curated set of articles, metrics, events, notes, or an AI answer. It may be
-  short, but the planner is designed to distill larger sources into a concise
-  video rather than represent every fact;
-- `knowledgeMode`: `input-only` by default, or `general` when stable model
-  knowledge may supplement the request;
-- `instructions`: optional creative direction that cannot override facts;
-- `opening`: optional custom copy for the deterministic opening; omission uses
-  `Creating your video...`, while `false` lets the host render loading UI
-  without adding an opening scene to the video;
-- `personalization`: application-defined fields such as name, role, account,
-  period, goal, or onboarding partner;
-- `brand`: an optional background preset plus name, logo, font, surfaces, and
-  advanced exact tokens;
-- `suppliedMedia`: approved images or videos with a role and description;
-- `audio`: omit for automatic selection, pass `{ src }`, or use `false` for silence;
-- `orientation` and `maxDurationSec`: composition constraints.
+The viewer sends a prompt with bounded completed conversation turns. The server
+adds trusted application `instructions`, template capabilities, and the selected
+visual mode. `VideoChat` options control brand, style, orientation, and custom
+templates. Exact facts belong in the authorized prompt or conversation; secrets
+and provider configuration stay on the server.
+
+See [Prompt and conversation input](prompt-and-input.md) for the request contract.
 
 ## Template kit
 
@@ -72,20 +60,10 @@ another streaming text model.
 The planner does not create public event IDs, checksums, or final
 snapshots. The runtime owns those guarantees.
 
-`createVideoHandler` asks the planner to emit one early
-`scene.add` with `placement: "closer"` after the first playable body scene.
-That placement is planner-only: the runtime holds the validated closer,
-reserves its readable duration while later body scenes stream, and appends it
-last without persisting `placement` into the completed `Video`.
-
-| Boundary | Type | Owner |
-| --- | --- | --- |
-| Planner parts | Internal validated plan data | Server/provider adapter |
-| Values read from `response.stream` | `VideoEvent` | SDK runtime |
-| Terminal editable result | `Video` via `response.result` | SDK reducer |
-
-A planner must never yield `VideoEvent` envelopes. It yields plan
-parts; the runtime validates them and creates the public event metadata.
+The internal composition pipeline can reserve a validated closing scene and
+append it after the body. Planner parts are internal data; applications connect
+text callbacks to `createVideoChatHandler` and let the SDK own event envelopes,
+sequence IDs, and final snapshots.
 
 ## Event stream
 
@@ -93,21 +71,19 @@ The runtime emits ordered protocol events:
 
 ```text
 response.start
-audio.set             optional, before any scene
-scene.add             supplied opening
+data.video-chat-opening short spoken hook
 scene.add             generated body
 scene.add             generated body
 scene.add             reserved closer
 response.complete     exact terminal snapshot
 ```
 
-Network transport uses SSE. Direct in-process integrations expose the same
-events as an async iterable.
+Network transport uses SSE. Test utilities can simulate protocol events in process.
 
 ## Playback and buffering
 
 The player renders the first committed scene and continues through the known
-timeline. Audio can loop during a generation gap. A media-bearing scene should
+timeline. The chat holds its current visual during a generation gap. A media-bearing scene should
 not be committed until its asset is ready; start generated content with a
 typography-led scene so useful playback does not wait on media lookup.
 
@@ -124,8 +100,8 @@ complete storage contract.
 ## Completion snapshot
 
 `response.complete` contains the exact reduced `Video` plus a
-checksum. Persist the snapshot when you need replay, resume, export, analytics,
-or an editing handoff. The event log can also be persisted and revalidated.
+checksum. The chat retains the completed video on its turn for application-owned replay
+and storage. A partial playable answer may complete with non-fatal warnings.
 
 Read the complete [Protocol 0.5](reference/protocol.md) and the separate
 [persisted Video 0.1 contract](persistence.md).

package/docs/custom-templates.md

@@ -1,4 +1,4 @@
-[← Documentation home](../README.md) · [Previous: Branding and personalization](branding-and-personalization.md) · [Next: Motion and effects →](motion-and-effects.md)
+[← Documentation home](../README.md) · [Previous: Customization](customization.md) · [Next: Motion and effects →](motion-and-effects.md)
 
 # Custom templates
 
@@ -190,7 +190,6 @@ Start from the generated file or one of the packaged references:
 | --- | --- |
 | One headline and supporting line | [Minimal text](../examples/custom-template/minimal-text.tsx) |
 | One exact metric and its change | [Structured data](../examples/custom-template/structured-data.tsx) |
-| An application-supplied image | [Supplied media](../examples/custom-template/supplied-media.tsx) |
 
 The [reference comparison](../examples/custom-template/README.md) explains when
 to choose each. Copy a file into `vanillasky/templates/`, change its ID and
@@ -213,18 +212,27 @@ selection, and validator. Import it in the route that connects your model:
 
 ```ts
 // src/video-route.ts
-import { streamText } from "ai";
-import { createVideoHandler } from "@vanillaskyai/video/server";
+import { generateText, streamText } from "ai";
+import { createVideoChatHandler } from "@vanillaskyai/video/server";
 import { videoModel } from "./video-model";
 import { templates } from "../vanillasky/server";
 
-export const handleVideo = createVideoHandler({
+export const handleVideoChat = createVideoChatHandler({
   templates,
   authorize: (request) => {
     if (process.env.VANILLASKY_LOCAL_DEMO !== "1") return false;
     const hostname = new URL(request.url).hostname;
     return hostname === "localhost" || hostname === "127.0.0.1";
   },
+  generateText: async ({ systemPrompt, userPrompt, signal }) => {
+    const result = await generateText({
+      model: videoModel,
+      system: systemPrompt,
+      prompt: userPrompt,
+      abortSignal: signal,
+    });
+    return result.text;
+  },
   streamText: ({ systemPrompt, userPrompt, signal }) => streamText({
     model: videoModel,
     system: systemPrompt,
@@ -242,19 +250,13 @@ check before deployment, as shown in
 Use the browser registry for generation and playback:
 
 ```tsx
-// src/video-composer.tsx
-import { VideoPlayer, useVideo } from "@vanillaskyai/video/react";
+// src/video-chat.tsx
+import { VideoChat } from "@vanillaskyai/video/react";
+import "@vanillaskyai/video/video-chat.css";
 import { templates } from "../vanillasky";
 
-export function VideoComposer() {
-  const video = useVideo({ templates });
-
-  return <>
-    <button onClick={() => void video.generate({ input: "Grounded answer" })}>
-      Generate
-    </button>
-    <VideoPlayer {...video.playerProps} />
-  </>;
+export function App() {
+  return <VideoChat options={{ templates }} />;
 }
 ```
 
@@ -311,8 +313,7 @@ export function TemplatePreview() {
 
 Change the saved variables to each named example, inspect both orientations,
 and play the scene to inspect its full progress range. This is also the
-production replay path for a completed video saved from
-`await video.generate(...)`.
+production replay path for a completed chat turn saved from `chat.turns`.
 
 ## Schema and grounding
 
@@ -330,14 +331,17 @@ Useful formats add grounding behavior:
 - `grounded-stat` marks numeric statistical evidence for the planner; it does
   not compare the value against raw input at runtime;
 - `grounded-quote` requires the quote to exist verbatim in the input;
-- `supplied-image` requires an image URL listed in `VideoInput.suppliedMedia`;
-- `uri` applies the supplied-media or server URL policy to an approved URL;
+- `uri` validates approved media URLs restored by the server;
 - `stock-media-keyword` is only for hosts that resolve stock media before a
   scene is committed.
 
 Templates whose core proof needs a real statistic can add
-`"x-vanillasky": { "requiresStat": true }`. See the structured-data and
-supplied-media references for complete examples.
+`"x-vanillasky": { "requiresStat": true }`. See the structured-data reference for a complete example.
+
+For media-backed chat scenes, copy the built-in `media` template and keep its
+`mediaKeyword`, `mediaUrl`, and `mediaType` contract. Configure `searchMedia` on
+the chat handler so the server resolves semantic searches into approved assets.
+The chat request does not accept a separate supplied-media input list.
 
 The automatic `opening` uses the built-in `media` variables (`texts` and
 `mediaType: "gradient"`). If you replace `media` while using automatic
@@ -353,5 +357,5 @@ trusted template and fills its declared schema; it never writes executable UI
 code.
 
 For the exact request path and source locations, see
-[Architecture](architecture.md). For media policies and supplied-media input,
+[Architecture](architecture.md). For media policies and provider callbacks,
 see [Media and audio](media-and-audio.md).

package/docs/customization.md

@@ -4,9 +4,11 @@
 
 ## Video chat interface
 
-The default `VideoChat` interface is already responsive and accessible. Pass a
-custom welcome heading and a root class when the application needs its own copy
-or chrome colors:
+The default `VideoChat` uses an immersive video canvas with a floating
+conversation field, on-video subtitles, and a single dark settings/history
+treatment. See [interface behavior](immersive-interface.md) and the
+[component reference](reference/design-system.html). Pass a custom welcome
+heading and a root class when the application needs its own copy or chrome colors:
 
 ```tsx
 <VideoChat
@@ -22,21 +24,25 @@ that instance:
 
 ```css
 .acme-chat {
-  --vs-accent: #0057ff;
-  --vs-accent-deep: #003fb8;
+  --vs-media-glass: rgb(18 24 40 / 80%);
+  --vs-media-text: #f8f8fc;
   --vs-voice: #e11d74;
   --vs-font: "Inter", sans-serif;
-  --vs-radius-lg: 1rem;
 }
 ```
 
+The built-in navigation carries the VanillaSky logo. `welcomeTitle` changes
+the welcome heading; it does not replace the navigation logo. `options.brand`
+styles generated video content independently of the surrounding controls.
+
 Use `options` for the endpoint, templates, orientation, visual brand, request
 headers, and an optional custom voice. Provider capabilities are discovered
 from the server. Use `useVideoChat()` only when the application needs to own the
 entire interface.
 
-The sections below customize lower-level, one-shot video composition. They are
-not required for the default chat.
+Pass the following visual settings through `VideoChat` or `useVideoChat` options.
+Keep viewer context in the prompt and completed conversation turns; use the
+server handler’s `instructions` for trusted product guidance.
 
 ## Background and semantic brand
 
@@ -96,35 +102,17 @@ These are defaults, not generated CSS. A validated scene may still select a
 more appropriate text or background treatment when its trusted template allows
 it.
 
-## Personalization
-
-`personalization` accepts JSON-safe application fields. Include only values the
-viewer is allowed to see. The system prompt treats them as context, not as
-instructions.
-
-Good fields include `firstName`, `role`, `accountName`, `period`, `goal`,
-`locale`, and `onboardingPartner`. Keep facts in `input` as well when they must
-appear in the story.
-
 ## Opening
 
-`VideoPlayer` automatically shows a brand-colored generation cover until the
-first validated scene arrives. The cover is player state, not video content: it
-is never written to the event log, replay, or export.
-
-The opening is deterministic and should not wait for an LLM or remote media.
-Omit it to use `Creating your video...`, or supply one concise custom sentence:
+The planner streams a short spoken hook before the scenes. The chat holds that
+opening until its speech finishes and the first scene is ready. A selected
+suggestion can start with its prewritten opening and already-loaded media:
 
 ```ts
-opening: "Your Q2 customer impact recap is ready."
+await chat.ask(card.prompt, { opening: card.opening, openingMedia: card.media });
 ```
 
-Pass `opening: false` to omit the persisted opening and show application-owned
-loading UI until the first generated scene arrives.
-
-Use `opening` only for a genuine opening that should remain in the completed
-response. VanillaSky infers the scene ID, `media` template, gradient variables,
-and three-second timing. Keep generic loading state in the host UI instead.
+Openings and scene narration share the chat voice and pause/mute controls.
 
 ## Aspect ratio and responsive layout
 
@@ -138,31 +126,11 @@ should display landscape on desktop and portrait on mobile without changing the
 saved response, pass `orientation="auto"` to `VideoPlayer`; it responds
 to its container width. See [responsive orientation](responsive-orientation.md).
 
-## Supplied media
-
-Provide approved media with semantic descriptions:
-
-```ts
-suppliedMedia: [{
-  id: "product-dashboard",
-  url: "https://cdn.example.com/dashboard.png",
-  type: "image",
-  description: "Activation dashboard after the Q2 release",
-  role: "product",
-}]
-```
-
-Resolve searched media before generation and pass the approved result through
-`suppliedMedia`. See [media providers](media-and-audio.md#media-providers).
-
-## Soundtrack audio
+## Media and voice
 
-Pass `audio: { src }` for a specific track, omit `audio` to let the server choose
-synchronously from a preloaded catalog, or pass `audio: false` for silence.
-VanillaSky infers deterministic duration, volume, beat, and fade-out metadata.
-The soundtrack should continue across visual generation gaps and finish with
-the final scene. `VideoChat` separately owns narration, TTS integration, browser
-voice fallback, and speech synchronization for conversational responses.
+Configure `searchMedia`, `generateVideo`, and `generateSpeech` on the server
+handler. They progressively enhance the same chat; failed optional providers
+fall back to templates or browser voice. See [Media and voice](media-and-audio.md).
 
 ## Custom templates
 

package/docs/errors.md

@@ -2,71 +2,61 @@
 
 # Errors and recovery
 
-Render errors in normal application UI outside the video. Never show stack traces, provider details, raw deltas, or protocol diagnostics inside a scene.
-
-| Boundary | Example codes | Host response |
-| --- | --- | --- |
-| HTTP | `unauthorized`, `origin_forbidden`, `body_too_large` | Fix session/policy; do not retry blindly |
-| Input | `invalid_json`, `invalid_request`, `secret_field` | Correct client request |
-| Protocol | invalid sequence/checksum/scene | Stop the stream and record a safe diagnostic |
-| Generation | `generation_failed` | Hold current scene, end cleanly, offer retry |
-| Generated part | `invalid_generated_part` | Keep accepted scenes; inspect the private server log |
-| Resume | `invalid_cursor`, `resume_unavailable` | Restart only before visible output or from valid storage |
-
-```tsx
-import { VideoError } from "@vanillaskyai/video/react";
-
-try {
-  const completed = await video.generate({ input });
-  await saveVideo(completed);
-} catch (error) {
-  if (error instanceof VideoError) {
-    logSafeFailure({
-      code: error.code,
-      status: error.status,
-      requestId: error.requestId,
-      runId: error.runId,
-    });
-  }
-}
-```
-
-`generate()` resolves only for `response.complete`. A terminal
-`response.error` or `response.abort` rejects it. The hook still retains the
-latest validated `video.video`, and its player stream still receives terminal
-events, so an application may keep already accepted scenes visible while it
-offers a retry. If the planner already supplied a validated reserved closer,
-the runtime appends it to that playable terminal snapshot before reporting a
-late provider failure; it never invents or rewrites closer copy during recovery.
-
-Both a server `response.abort` and an explicit `video.abort(reason)` keep
-`video.status` at `aborted`; `video.error` contains the same safe typed abort
-reported by the rejected `generate()` promise.
-
-`VideoError` preserves only actionable public context: the server's safe
-`code` and `message`, HTTP `status` when available, `requestId`, `runId`, and
-`recoverable`. Do not replace those fields with raw provider errors.
-
-Abort replaced compositions and client disconnects. Retry provider throttles or transient failures only within an explicit request/time budget and only before visible output unless you have validated resume storage. Never silently restart after the viewer has begun watching.
-
-Log safe codes with request/run IDs and latency. Keep private provider messages in server logs through `onError`; redact source, personalization, keys, tokens, and signed URLs.
-
-Live acceptance artifacts use stable failure categories: `network`,
-`authentication`, `model_not_found`, `rate_limit`, `provider`, `planner_parse`,
-`scene_validation`, or `unknown`. Before diagnosing the SDK, probe the provider
-with one minimal request using the same server-only credential and model. Check
-DNS/proxy access, credential validity, model availability, account/rate limits,
-and timeout settings in that order. Never copy raw provider payloads, streamed
-deltas, prompts, or credentials into browser errors or CI artifacts.
-
-Server handlers drop invalid generated parts by default. Each rejection calls
-`onError` with the full internal reason, while the browser receives only the
-recoverable `invalid_generated_part` diagnostic. Set `invalidPartBehavior: "fail"`
-only when fail-fast generation is an intentional compatibility requirement.
-
-`onComplete` runs exactly once only after `response.complete`. Terminal errors,
-client disconnects, explicit aborts, and host timeouts do not call it;
-`onError` receives internal failures, while cancellation remains a safe
-`response.abort`. Abort and timeout signals always propagate to `streamText`.
-The host owns timeout construction and retry policy. Do not retry invisibly
-after any scene has reached the viewer.
+`VideoChat` preserves the opening and accepted scenes when an optional scene,
+provider, or stream fails. It recovers silently and keeps the answer playable. A fatal error is shown only when no playable response can
+be produced. Never put provider details or stack traces in the interface.
+
+## Recovery by boundary
+
+| Failure | Result |
+| --- | --- |
+| Invalid planner scene | Skip the part and accept later valid scenes |
+| Generated footage | Try stock media, matching completed footage, then a safe template |
+| Stock lookup or candidate | Continue with another candidate or template |
+| Template renderer | Isolate the failed scene with a safe visual |
+| Missing narration | Continue with scene text |
+| Generated speech | Use browser voice |
+| Late stream failure | Keep playable opening and completed scenes |
+| Unauthorized or invalid request without playable output | Show a safe error |
+
+Keep non-fatal `chat.warnings` as application diagnostics; they are also
+retained on the corresponding `VideoChatTurn.warnings`. Render `chat.error`
+when the response cannot play, and keep `chat.playerProps` mounted during recovery.
+Check `turn.completed` before persisting it as completed conversation context;
+a cancelled or partial visible turn is not automatically a completed turn.
+
+`VideoError` exposes actionable public fields: `code`, `message`, optional HTTP
+`status`, `requestId`, `runId`, and `recoverable`. Log only safe codes and IDs
+from the client. The server's `onError` observer receives internal diagnostics;
+redact credentials, source data, provider payloads, and signed URLs before logging.
+Observer failures are isolated from response generation.
+
+## Cancellation and retries
+
+`chat.cancel()` cancels the current work while preserving available output.
+Replacing a prompt aborts its old providers and speech. The host must forward
+`signal` to every provider callback and own deadlines, quotas, and retry budgets.
+The chat retries once only before playback. Never silently restart generation
+after the viewer has begun watching, and do not replay paid generation requests
+without a deliberate idempotency and spend policy.
+
+The server drops invalid generated parts by default. `invalidPartBehavior: "fail"`
+is an explicit strict policy; ordinary chat should retain the resilient default.
+`onComplete` runs after a `response.complete`, including a recovered playable
+response. Fatal errors, disconnects, and explicit aborts do not call it.
+
+Automated regression and acceptance tests use mocked providers. See
+[Testing](testing.md) and the [chat acceptance gate](https://github.com/VanillaSkyAi/video/blob/main/docs/maintainers/acceptance.md).
+
+## Slow optional providers
+
+Generated video has a 15-second deadline per lookup. Stock media, generated
+speech preparation, and fallback scene narration have 3-second deadlines.
+A deadline uses the same safe fallback as a failed provider; completed scenes
+and scene order are preserved. Providers receive cancellation, and late results
+are ignored even when a provider does not cooperate. These initial limits bound
+waiting; they are not claims about measured live-provider performance.
+
+A completed turn and its saved video are available before follow-up suggestions.
+Suggestions load separately and may be omitted after a short deadline. Starting
+another turn or cancelling discards outstanding suggestions.

package/docs/getting-started.md

@@ -4,7 +4,8 @@
 
 The fastest VanillaSky integration is the complete, general-purpose video chat.
 It starts with packaged templates and browser voice, then turns on optional
-speech, stock, transcription, and generated video when their server keys exist.
+speech and generated video when you install their adapters and add server keys.
+Stock media needs only its server key.
 
 ## Create the app
 
@@ -15,7 +16,9 @@ npx @vanillaskyai/video init
 ```
 
 Init installs the exact SDK version that ran it, creates a small application
-shell, and installs its provider dependencies.
+shell, installs baseline dependencies, and runs doctor automatically. Optional
+speech and video packages are not installed. If installation is interrupted,
+rerun the same init command to finish setup.
 It does not copy VanillaSky's template tree. The important generated files are:
 
 | File | Your application owns |
@@ -59,23 +62,27 @@ variable. Then inspect the setup without calling any provider:
 npx vanillasky doctor
 ```
 
-The base experience reports `templates + browser voice`. A ready text key makes
-the chat answer. Optional keys progressively add capabilities:
+The base experience reports `templates + browser voice`. `ANTHROPIC_API_KEY`
+is the only required key. Doctor checks setup locally without calling providers
+and reports names and readiness, never values.
 
-```dotenv
-# Optional generated speech
-XAI_API_KEY=
+## Add optional capabilities
+
+Install only the capability you want:
 
-# Optional generated video and voice transcription
-FAL_KEY=
+```bash
+# Generated speech: installs the xAI adapter
+npx vanillasky providers add speech
 
-# Optional stock media
-PEXELS_API_KEY=
+# Generated video and transcription: installs the FAL adapter
+npx vanillasky providers add video
 ```
 
-Doctor reports only key names and readiness, never values. Adding or removing
-an optional key changes the available modes after a server restart; the client
-does not need to change.
+Add `XAI_API_KEY` for speech or `FAL_KEY` for video and transcription to
+`.env.local`, then restart the dev server. Stock media needs only
+`PEXELS_API_KEY`; no extra package or command is needed. The client stays the
+same. Rerun an interrupted provider command to finish its installation, then
+check readiness with `npx vanillasky doctor`.
 
 ## Run and verify