pipecat-ai · kompfner · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/.github/workflows/broken-links.yml b/.github/workflows/broken-links.yml
@@ -24,7 +24,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version-file: .nvmrc
 
       - name: Install Mintlify CLI
         run: npm install -g mint

diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
 .DS_Store
-.nvmrc
+node_modules/
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1 @@
+npx lint-staged
diff --git a/.nvmrc b/.nvmrc
@@ -0,0 +1 @@
+24.19.0
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,33 +2,39 @@
 
 ## Project overview
 
-This is the documentation site for [Pipecat](https://github.com/pipecat-ai/pipecat), hosted at [docs.pipecat.ai](https://docs.pipecat.ai). It's built with [Mintlify](https://mintlify.com/) and contains ~314 MDX files covering guides, API references, and deployment docs.
+This is the documentation site for [Pipecat](https://github.com/pipecat-ai/pipecat), hosted at [docs.pipecat.ai](https://docs.pipecat.ai). It's built with [Mintlify](https://mintlify.com/) and contains several hundred MDX files covering guides, API references, and deployment docs.
 
 ## Development commands
 
 ```bash
+# Install the Node version in .nvmrc, then dependencies and Git hooks
+nvm install
+npm install
+
 # Start local dev server
-mint dev
+npx mint dev
 
 # Check for broken links (also runs in CI)
-mint broken-links
+npx mint broken-links
 
-# Format files with Prettier
-npx prettier --write .
+# Format the whole site with Prettier
+npm run format
 ```
 
 ## Project structure
 
+The content directories correspond one-to-one with the navigation tabs in `docs.json`:
+
 ```
 docs.json          # Site config: navigation, tabs, theme, metadata
-getting-started/   # Intro, quickstart, ecosystem overview
-guides/            # Learning guides, feature how-tos
-server/            # Server-side framework reference (pipelines, services, utilities)
-client/            # Client SDK docs (JS, React, React Native, etc.)
-cli/               # Pipecat CLI reference
-deployment/        # Pipecat Cloud deployment docs
+overview/          # Intro and ecosystem overview
+pipecat/           # Pipecat framework docs (fundamentals, learn, features, telephony, deployment)
+client/            # Client SDK docs (concepts, guides)
+pipecat-flows/     # Pipecat Flows docs
+pipecat-cloud/     # Pipecat Cloud docs (fundamentals, guides, security)
+api-reference/     # Reference for server, client, CLI, Flows, and Cloud REST
 snippets/          # Reusable MDX snippets (shared across pages)
-images/            # Static images
+images/ logo/ videos/   # Static assets
 ```
 
 ## Content conventions
@@ -46,7 +52,7 @@ description: "Short description for SEO and navigation."
 
 ### Adding pages to navigation
 
-All pages must be registered in `docs.json` under `navigation.tabs[].groups[].pages`. The path is relative to the repo root without the `.mdx` extension (e.g., `"guides/learn/overview"`).
+All pages must be registered in `docs.json` under `navigation.tabs[].groups[].pages`. The path is relative to the repo root without the `.mdx` extension (e.g., `"overview/introduction"`).
 
 ### Mintlify components
 
@@ -68,6 +74,9 @@ Prettier is configured via `.prettierrc`:
 - Double quotes
 - Semicolons enabled
 
+A husky pre-commit hook runs lint-staged, which formats staged files. The whole
+site is Prettier-clean, so `npm run format` should be a no-op on a clean tree.
+
 ## CI/CD
 
 A GitHub Actions workflow (`.github/workflows/broken-links.yml`) runs `mint broken-links` on PRs and pushes to `main`. It comments on PRs if broken links are detected.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,8 +10,7 @@ This project follows the [Contributor Covenant v2.1](https://www.contributor-cov
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) 20+
-- [Mintlify CLI](https://www.npmjs.com/package/mint) (`npm i -g mint`)
+[nvm](https://github.com/nvm-sh/nvm), or another way to install the Node version pinned in `.nvmrc`.
 
 ### Setup
 
@@ -22,17 +21,29 @@ This project follows the [Contributor Covenant v2.1](https://www.contributor-cov
    cd docs
    ```
 
-2. Start the local dev server:
+2. Install and switch to the Node version this repo targets (see `.nvmrc`):
 
    ```bash
-   mint dev
+   nvm install
    ```
 
-3. Open `https://localhost:3000` in your browser to preview changes.
+3. Install dependencies. This also installs the Git hooks that format your changes on commit:
+
+   ```bash
+   npm install
+   ```
+
+4. Start the local dev server:
+
+   ```bash
+   npx mint dev
+   ```
+
+5. Open `https://localhost:3000` in your browser to preview changes.
 
 ### Troubleshooting
 
-- **Mintlify dev isn't running** — Run `mint update` to get the latest version.
+- **Mintlify dev isn't running** — Run `npx mint update` to get the latest version.
 - **Page loads as a 404** — Make sure you are running in a folder with `docs.json`.
 
 ## Making a Contribution
@@ -45,25 +56,20 @@ This project follows the [Contributor Covenant v2.1](https://www.contributor-cov
 
 2. **Make your edits.** See the [Content Guidelines](#content-guidelines) below.
 
-3. **Format with Prettier** to match the repo style:
+3. **Check for broken links:**
 
    ```bash
-   npx prettier --write .
+   npx mint broken-links
    ```
 
-4. **Check for broken links:**
-
-   ```bash
-   mint broken-links
-   ```
-
-5. **Commit your changes** with a meaningful message:
+4. **Commit your changes** with a meaningful message. A pre-commit hook formats
+   the files you staged:
 
    ```bash
    git commit -m "Description of your changes"
    ```
 
-6. **Push your branch** and open a Pull Request against `main`:
+5. **Push your branch** and open a Pull Request against `main`:
 
    ```bash
    git push origin your-branch-name
@@ -89,21 +95,23 @@ description: "Short description for SEO and navigation."
 All pages must be registered in `docs.json` under `navigation.tabs[].groups[].pages`. The path is relative to the repo root without the `.mdx` extension:
 
 ```
-"guides/learn/overview"
+"overview/introduction"
 ```
 
 ### Project Structure
 
+The content directories correspond one-to-one with the navigation tabs in `docs.json`:
+
 ```
 docs.json          # Site config: navigation, tabs, theme, metadata
-getting-started/   # Intro, quickstart, ecosystem overview
-guides/            # Learning guides, feature how-tos
-server/            # Server-side framework reference (pipelines, services, utilities)
-client/            # Client SDK docs (JS, React, React Native, etc.)
-cli/               # Pipecat CLI reference
-deployment/        # Pipecat Cloud deployment docs
+overview/          # Intro and ecosystem overview
+pipecat/           # Pipecat framework docs (fundamentals, learn, features, telephony, deployment)
+client/            # Client SDK docs (concepts, guides)
+pipecat-flows/     # Pipecat Flows docs
+pipecat-cloud/     # Pipecat Cloud docs (fundamentals, guides, security)
+api-reference/     # Reference for server, client, CLI, Flows, and Cloud REST
 snippets/          # Reusable MDX snippets (shared across pages)
-images/            # Static images
+images/ logo/ videos/   # Static assets
 ```
 
 ### Mintlify Components
@@ -128,14 +136,19 @@ Prettier is configured via `.prettierrc`:
 - Double quotes
 - Semicolons enabled
 
-Run `npx prettier --write .` before committing to ensure consistent formatting.
+A pre-commit hook (husky + lint-staged) formats staged files, so formatting is
+usually taken care of for you. To format the whole site by hand:
+
+```bash
+npm run format
+```
 
 ## Continuous Integration
 
 A GitHub Actions workflow runs `mint broken-links` on every PR and push to `main`. If broken links are detected, the workflow will fail and post a comment on your PR. You can run the same check locally:
 
 ```bash
-mint broken-links
+npx mint broken-links
 ```
 
 ## Getting Help

diff --git a/api-reference/cli/cloud/auth.mdx b/api-reference/cli/cloud/auth.mdx
@@ -63,8 +63,8 @@ pipecat cloud auth use-pat <token>
 
 <Tip>
   You can also set the `PIPECAT_TOKEN` environment variable instead of storing
-  the token locally. See the [PAT guide](/pipecat-cloud/guides/personal-access-tokens)
-  for details.
+  the token locally. See the [PAT
+  guide](/pipecat-cloud/guides/personal-access-tokens) for details.
 </Tip>
 
 ## whoami

diff --git a/api-reference/cli/cloud/build.mdx b/api-reference/cli/cloud/build.mdx
@@ -20,7 +20,8 @@ pipecat cloud build logs [OPTIONS] BUILD_ID
 **Arguments:**
 
 <ParamField path="build_id" type="string" required>
-  The ID of the build to get logs for. You can find build IDs using `pipecat cloud build list`.
+  The ID of the build to get logs for. You can find build IDs using `pipecat
+  cloud build list`.
 </ParamField>
 
 **Options:**
@@ -30,7 +31,8 @@ pipecat cloud build logs [OPTIONS] BUILD_ID
 </ParamField>
 
 <ParamField path="--organization / -o" type="string">
-  Organization to use. If not provided, uses the current organization from your configuration.
+  Organization to use. If not provided, uses the current organization from your
+  configuration.
 </ParamField>
 
 ## status
@@ -52,7 +54,8 @@ pipecat cloud build status [OPTIONS] BUILD_ID
 **Options:**
 
 <ParamField path="--organization / -o" type="string">
-  Organization to use. If not provided, uses the current organization from your configuration.
+  Organization to use. If not provided, uses the current organization from your
+  configuration.
 </ParamField>
 
 The status command displays detailed build information including:
@@ -80,15 +83,17 @@ pipecat cloud build list [OPTIONS]
 </ParamField>
 
 <ParamField path="--status / -s" type="string">
-  Filter by build status. Valid values: `pending`, `building`, `success`, `failed`, `timeout`.
+  Filter by build status. Valid values: `pending`, `building`, `success`,
+  `failed`, `timeout`.
 </ParamField>
 
 <ParamField path="--region / -r" type="string">
   Filter by region.
 </ParamField>
 
 <ParamField path="--organization / -o" type="string">
-  Organization to use. If not provided, uses the current organization from your configuration.
+  Organization to use. If not provided, uses the current organization from your
+  configuration.
 </ParamField>
 
 ## Examples

diff --git a/api-reference/cli/init.mdx b/api-reference/cli/init.mdx
@@ -34,8 +34,8 @@ pipecat init [TARGET_DIR] [OPTIONS]
 **Guide options:**
 
 <ParamField path="--overwrite-guide" type="boolean" default="false">
-  Overwrite existing `AGENTS.md`, `CLAUDE.md`, and `GETTING_STARTED.md` files. By
-  default existing guide files are kept, so your edits are never clobbered.
+  Overwrite existing `AGENTS.md`, `CLAUDE.md`, and `GETTING_STARTED.md` files.
+  By default existing guide files are kept, so your edits are never clobbered.
 </ParamField>
 
 **Scaffold options:** Passing any of these (or `--config`) scaffolds a bot non-interactively, in-place in `TARGET_DIR`.

diff --git a/api-reference/client/android/overview.mdx b/api-reference/client/android/overview.mdx
@@ -59,7 +59,11 @@ client.startBotAndConnect(startBotParams).withCallback {
 ## Documentation
 
 <CardGroup cols={2}>
-  <Card title="API Reference" icon="book" href="/api-reference/client/android/api-reference">
+  <Card
+    title="API Reference"
+    icon="book"
+    href="/api-reference/client/android/api-reference"
+  >
     SDK API documentation
   </Card>
   <Card

diff --git a/api-reference/client/android/transports/gemini-websocket.mdx b/api-reference/client/android/transports/gemini-websocket.mdx
@@ -68,24 +68,24 @@ client.connect(
 
 `connect()` takes a `GeminiServiceOptions`:
 
-| Parameter | Type | Description |
-|---|---|---|
-| `apiKey` | `String` | Your Gemini API key |
-| `modelConfig` | `Value` | Model setup for the Live API (model name, generation config, system instruction, tools) |
-| `initialUserMessage` | `String?` | Optional message to send at session start |
+| Parameter            | Type      | Description                                                                             |
+| -------------------- | --------- | --------------------------------------------------------------------------------------- |
+| `apiKey`             | `String`  | Your Gemini API key                                                                     |
+| `modelConfig`        | `Value`   | Model setup for the Live API (model name, generation config, system instruction, tools) |
+| `initialUserMessage` | `String?` | Optional message to send at session start                                               |
 
 ### GeminiServiceOptions.withDefaults
 
 For common cases, `GeminiServiceOptions.withDefaults()` builds the `modelConfig` for you (audio output with the given voice):
 
-| Parameter | Type | Description |
-|---|---|---|
-| `apiKey` | `String` | Your Gemini API key |
-| `model` | `String` | Model name (default: `"models/gemini-3.1-flash-live-preview"`) |
-| `initialUserMessage` | `String?` | Optional message to send at session start |
-| `voice` | `String` | Voice name (default: `"Puck"`) |
-| `systemInstruction` | `Value?` | Optional system instruction |
-| `tools` | `Value.Array` | Optional tools/function definitions |
+| Parameter            | Type          | Description                                                    |
+| -------------------- | ------------- | -------------------------------------------------------------- |
+| `apiKey`             | `String`      | Your Gemini API key                                            |
+| `model`              | `String`      | Model name (default: `"models/gemini-3.1-flash-live-preview"`) |
+| `initialUserMessage` | `String?`     | Optional message to send at session start                      |
+| `voice`              | `String`      | Voice name (default: `"Puck"`)                                 |
+| `systemInstruction`  | `Value?`      | Optional system instruction                                    |
+| `tools`              | `Value.Array` | Optional tools/function definitions                            |
 
 ### Audio devices
 

diff --git a/api-reference/client/android/transports/openai-webrtc.mdx b/api-reference/client/android/transports/openai-webrtc.mdx
@@ -8,8 +8,8 @@ The OpenAI Realtime WebRTC transport implementation enables real-time audio comm
 <Note>
   Transports of this type connect directly to OpenAI's API from the client,
   which exposes your API key. This is designed primarily for development and
-  testing. For production applications, proxy through a server component to
-  keep credentials secure.
+  testing. For production applications, proxy through a server component to keep
+  credentials secure.
 </Note>
 
 ## Installation
@@ -73,26 +73,26 @@ client.connect(
 
 ### OpenAIServiceOptions
 
-| Parameter | Type | Description |
-|---|---|---|
-| `apiKey` | `String` | Your OpenAI API key |
-| `sessionConfig` | `OpenAIRealtimeSessionConfig` | Session configuration |
-| `model` | `String?` | Model name (default: `"gpt-realtime"`) |
-| `initialMessages` | `List<LLMContextMessage>` | Messages to inject at session start |
+| Parameter         | Type                          | Description                            |
+| ----------------- | ----------------------------- | -------------------------------------- |
+| `apiKey`          | `String`                      | Your OpenAI API key                    |
+| `sessionConfig`   | `OpenAIRealtimeSessionConfig` | Session configuration                  |
+| `model`           | `String?`                     | Model name (default: `"gpt-realtime"`) |
+| `initialMessages` | `List<LLMContextMessage>`     | Messages to inject at session start    |
 
 ### OpenAIRealtimeSessionConfig
 
-| Parameter | Type | Description |
-|---|---|---|
-| `modalities` | `List<String>?` | Output modalities (e.g. `["audio", "text"]`), sent to the API as `output_modalities` |
-| `instructions` | `String?` | System instructions for the model |
-| `voice` | `String?` | Voice name (e.g. `"alloy"`, `"ballad"`) |
-| `turnDetection` | `Value?` | Turn detection config |
-| `inputAudioNoiseReduction` | `Value?` | Noise reduction config |
-| `inputAudioTranscription` | `Value?` | Transcription model config |
-| `tools` | `Value?` | Tool/function definitions |
-| `toolChoice` | `String?` | Tool choice strategy |
-| `temperature` | `Float?` | Deprecated — not supported by the GA Realtime API, this value is ignored |
+| Parameter                  | Type            | Description                                                                          |
+| -------------------------- | --------------- | ------------------------------------------------------------------------------------ |
+| `modalities`               | `List<String>?` | Output modalities (e.g. `["audio", "text"]`), sent to the API as `output_modalities` |
+| `instructions`             | `String?`       | System instructions for the model                                                    |
+| `voice`                    | `String?`       | Voice name (e.g. `"alloy"`, `"ballad"`)                                              |
+| `turnDetection`            | `Value?`        | Turn detection config                                                                |
+| `inputAudioNoiseReduction` | `Value?`        | Noise reduction config                                                               |
+| `inputAudioTranscription`  | `Value?`        | Transcription model config                                                           |
+| `tools`                    | `Value?`        | Tool/function definitions                                                            |
+| `toolChoice`               | `String?`       | Tool choice strategy                                                                 |
+| `temperature`              | `Float?`        | Deprecated — not supported by the GA Realtime API, this value is ignored             |
 
 ### Audio devices