Summary

• Adds a new documentation page (fern/chat/variable-substitution.mdx) explaining how variableValues behave when using sessions with the Chat API
• Updates fern/docs.yml to add the new page to the Chat section navigation

What this documents

This page explains a critical behavior that developers need to understand:

1. Variables are "baked in" at session creation - When you pass assistantOverrides.variableValues in POST /session, the template placeholders (e.g., {{name}}) are immediately substituted and the pre-substituted assistant is stored
2. Subsequent chats use the pre-substituted assistant - Chat requests with just sessionId automatically use the stored values
3. New variableValues in chat requests have no effect - Because the {{}} placeholders no longer exist in the stored assistant
4. Fresh templates can override - If you need different values mid-session, you must provide a new template with {{}} placeholders along with new variableValues

Content includes

• Overview of how variable substitution works
• Step-by-step explanation of session creation and chat creation behavior
• Code examples in cURL, TypeScript, and Python
• Quick reference table summarizing all scenarios
• Best practices section with accordion-based recommendations
• Links to related documentation

Test plan

• Verify the new page renders correctly in the Fern docs preview
• Check that navigation link appears correctly in the Chat section
• Validate all code examples are syntactically correct
• Confirm internal links resolve properly

Closes VAP-11219

🤖 Generated with Claude Code