VapiAI · goosewin · Jun 3, 2025 · Jun 4, 2025 · Jun 4, 2025 · Jun 4, 2025
diff --git a/.cursor/rules/always-applied/core-principles.mdc b/.cursor/rules/always-applied/core-principles.mdc
@@ -0,0 +1,36 @@
+---
+description: Core documentation principles and writing standards
+globs: 
+alwaysApply: true
+---
+
+# Core Documentation Principles
+
+Provide developers with documentation that is quick to read, easy to follow, and immediately actionable.
+
+## Writing Style & Tone
+
+| Guideline | Why it matters |
+|-----------|---------------|
+| **Active voice** | "Connect the SDK" is clearer than "The SDK should be connected." |
+| **Present tense** | Keeps instructions straightforward (e.g., "Run" not "You will run"). |
+| **Second‑person ("you")** | Speaks directly to the reader. Reserve "we" for collaborative tutorials. |
+| **Explain intent before action** | Briefly state *why* a step is needed, then show *how*. |
+| **Concrete examples over theory** | Code snippets and visuals anchor concepts. |
+| **Consistent terminology** | Define a term once; reuse it exactly the same everywhere. |
+| **Parallel structure** | Lists and headings should follow consistent grammatical patterns. |
+| **Descriptive link text** | Use "view the guide" rather than "click here." |
+| **Comment code sparsely** | Only where intent isn't obvious from variable/function names. |
+
+> **Rule of thumb**: every sentence should either clarify *why* or *how*—if it does neither, remove or rewrite it.
+
+## Style Rules
+
+- **Tone**: Direct, professional, friendly
+- Break up large blocks of text with line‑breaks
+- Avoid marketing or promotional wording
+- Link to related pages when helpful, especially the **API reference** at `/fern/api-reference`
+- Use **bold** text to emphasize key names or concepts
+- **Titles**: Capitalize only the first word unless a proper noun is used
+- **Subtitles**: Begin with *Learn to …* for guides; otherwise keep them concise and factual
+- **Emojis / decorative icons**: Use only when essential for comprehension 
diff --git a/.cursor/rules/always-applied/fern-components.mdc b/.cursor/rules/always-applied/fern-components.mdc
@@ -0,0 +1,224 @@
+---
+description: Fern documentation framework components and features
+globs: 
+alwaysApply: true
+---
+
+# Fern Components & Framework Features
+
+Fern is our documentation framework. Use Fern-specific components and features for enhanced functionality.
+
+## Code Blocks & Syntax Highlighting
+
+### Multi-language Code Blocks with Tabs
+Use `<CodeBlocks>` for multiple language examples that automatically synchronize:
+
+```mdx
+<CodeBlocks>
+```typescript title="TypeScript SDK"
+import { VapiClient } from "@vapi-ai/server-sdk";
+
+const client = new VapiClient({ token: process.env.VAPI_API_KEY });
+```
+```python title="Python SDK"
+from vapi import Vapi
+
+client = Vapi(token=os.getenv("VAPI_API_KEY"))
+```
+```bash title="cURL"
+curl -X POST "https://api.vapi.ai/assistant" \
+     -H "Authorization: Bearer $VAPI_API_KEY"
+```
+</CodeBlocks>
+```
+
+### Code Block Features
+Enhance code blocks with these attributes:
+- `title="filename.ext"` - Add file title
+- `{2-4}` - Highlight specific lines
+- `focus` - Focus on specific lines
+- `maxLines=10` - Limit visible lines (default: 20)
+- `wordWrap` - Wrap long lines instead of scrolling
+
+```mdx
+```typescript title="example.ts" {2-3} maxLines=15 wordWrap
+const config = {
+  apiKey: process.env.VAPI_API_KEY, // highlighted
+  timeout: 30000 // highlighted
+};
+```
+```
+
+## Callouts & Alerts
+
+Use semantic callouts to highlight important information:
+
+```mdx
+<Tip>Helpful tips and best practices</Tip>
+<Note>Important information to remember</Note>
+<Warning>Cautions and potential issues</Warning>
+<Error>Critical errors and troubleshooting</Error>
+<Info>Additional context and explanations</Info>
+<Check>Success confirmations and completed tasks</Check>
+```
+
+## Interactive Components
+
+### Accordions for Collapsible Content
+Perfect for FAQs and optional details:
+
+```mdx
+<AccordionGroup>
+  <Accordion title="Common question">
+    Detailed answer with searchable content (Cmd+F works even when collapsed)
+  </Accordion>
+  <Accordion title="Another question">
+    More detailed explanations
+  </Accordion>
+</AccordionGroup>
+```
+
+### Tabs for Related Content
+Use for different approaches or languages:
+
+```mdx
+<Tabs>
+  <Tab title="Dashboard">
+    Visual, no-code approach with screenshots
+  </Tab>
+  <Tab title="SDK">
+    Programmatic implementation
+  </Tab>
+</Tabs>
+```
+
+### Steps for Sequential Processes
+Automatically numbered with anchor links:
+
+```mdx
+<Steps>
+  <Step title="Set up your account">
+    Create your Vapi account and get your API key
+  </Step>
+  <Step title="Install the SDK">
+    Install using your preferred package manager
+  </Step>
+  <Step title="Make your first call">
+    Create your first assistant
+  </Step>
+</Steps>
+```
+
+## Cards & Navigation
+
+### Individual Cards
+```mdx
+<Card title="Python SDK" icon="brands python" href="/docs/sdks/python">
+  Get started with Vapi's Python SDK
+</Card>
+```
+
+### Card Groups for Options
+```mdx
+<CardGroup cols={2}>
+  <Card title="Quickstart" icon="rocket" href="/docs/quickstart">
+    **Best for:** First-time users
+
+    Get up and running in 5 minutes
+  </Card>
+  <Card title="Advanced Setup" icon="cog" href="/docs/advanced">
+    **Best for:** Production deployments
+
+    Configure advanced features
+  </Card>
+</CardGroup>
+```
+
+## Content Layout
+
+### Aside for Sticky Content
+Push content to the right in a sticky container:
+
+```mdx
+<Aside>
+  <EndpointRequestSnippet endpoint='POST /assistant' />
+</Aside>
+```
+
+### Frames for Images
+Wrap images in a styled container:
+
+```mdx
+<Frame caption="Assistant configuration dashboard">
+  <img src="/assets/images/dashboard.png" alt="Dashboard screenshot" />
+</Frame>
+```
+
+## API Reference Components
+
+### Endpoint Snippets
+Reference API endpoints directly:
+
+```mdx
+<EndpointRequestSnippet endpoint='POST /assistant' />
+<EndpointResponseSnippet endpoint='POST /assistant' />
+<EndpointSchemaSnippet endpoint='POST /assistant' />
+```
+
+### Parameter Documentation
+Use structured parameter tables:
+
+```mdx
+<ParamField path="name" type="string" required>
+  The name of your assistant
+</ParamField>
+<ParamField path="model" type="string" default="gpt-4">
+  The LLM model to use
+</ParamField>
+```
+
+## Advanced Features
+
+### Embeds for Rich Media
+```mdx
+<Embed src="/assets/demo-video.mp4" />
+<Embed src="/assets/api-spec.pdf" />
+```
+
+### Icons from Font Awesome
+```mdx
+<Icon icon="rocket" />
+<Icon icon="brands github" />
+```
+
+### Tooltips for Contextual Help
+```mdx
+<Tooltip tip="Your API key from the dashboard">
+  API Key
+</Tooltip>
+```
+
+## Best Practices
+
+### Component Selection
+- **CodeBlocks** - For multi-language examples that should sync
+- **Tabs** - For different approaches to the same task
+- **Steps** - For sequential procedures
+- **Cards** - For navigation and option selection
+- **Accordions** - For optional details and FAQs
+- **Callouts** - For important information that needs attention
+
+### Content Organization
+- Use **Aside** for complementary content that shouldn't interrupt the main flow
+- Use **Frames** for important screenshots and diagrams
+- Use **CardGroups** to present multiple options clearly
+- Use **AccordionGroups** for comprehensive FAQ sections
+
+### Accessibility & Search
+- All accordion content is searchable even when collapsed
+- Components are built with accessibility in mind
+- Proper semantic HTML is generated for SEO
+
+---
+
+**Framework Note:** Fern automatically handles syntax highlighting, responsive design, and search indexing for all components.