docs: rewrite the Pipecat Flows docs around declarative flows

[markbackman]

Rewrites the Pipecat Flows docs around declarative flows, shipped in pipecat-ai/pipecat#5628.

The docs described Flows as a Python-only API. Pipecat main now ships FlowConfig and Flow, so a flow can be written as data, loaded at runtime, and joined to a small module of Python handlers. These pages start a new reader declarative and grow them into code when they need it. Both forms stay fully supported.

Written against Pipecat main at 397ddee2b.

What changed

Two new guide and reference pages. pipecat/flows/flow-configs sits after Quickstart; api-reference/pipecat-flows/flow-config and .../flow sit after the API Reference overview.

Quickstart is declarative end to end, built from examples/flows/yaml/hello_world/, closing with a link to the same flow in code.

Shared concept pages carry Declarative/Programmatic tab pairs, declarative first: Nodes & Messages, Actions, Context Strategies, State Management.

Functions documents the config entry shape, transition_only, branch tables, the (result, TRANSITION_IN_YAML) handler contract, and the shim pattern for transitions that depend on logic.

Placeholders are documented once, on State Management, with the insurance quote example. Other pages link to it.

Examples are grouped by form and the moved paths are fixed. Every link on that page was broken: the flat examples/flows/*.py files moved under yaml/ and python/.

API reference gains TRANSITION_IN_YAML, FlowReferenceError, and FlowProblem with its five codes; FlowManager gains config initialization and placeholder rendering.

One commit per page, so review can go page by page.

Verification

All four checks pass on the committed tree:

• npx mint broken-links --check-anchors --check-redirects
• npx mint validate
• node scripts/docs-meta-lint.mjs (0 errors; warnings 196 → 192)
• node scripts/check-imports.mjs against main at 397ddee2b

llms.txt and llms-full.txt regenerated.

Terminology greps come back clean: no "static", "dynamic", "YAML API", "Python API", or "variable" describes the two forms anywhere in the Flows pages.

Notes for the reviewer

examples/flows/README.md and the Flows bullet in src/pipecat/cli/agent_templates/AGENTS.md disagree about when to write a flow in code. The README gives four reasons; AGENTS.md gives three different ones, including "nodes are generated from a dataset", which the README does not have. These pages follow the README. Both sources also still say "YAML" and "Python" for the two forms, which this rewrite retires in favor of declarative and programmatic. Reconciling them is a Pipecat-side change.

The migration guide's Static Flows section gains one note: declarative flows are the successor, and the reused FlowConfig name does not accept the 1.0 format. That section's "What was removed" table still reads FlowConfig type → NodeConfig returned from functions, which is now only half the story. Left alone, since the plan scoped this page to the note.

main is not currently Prettier-clean. npm run format rewrites api-reference/server/services/s2s/thunderphone.mdx, api-reference/server/services/supported-services.mdx, api-reference/server/services/tts/silma.mdx, and gtm.js — trailing whitespace and misaligned tables in recently merged pages. Reverted here to keep this PR scoped; worth a separate cleanup.

Out of scope

The Flows editor's own docs and any claim about its export format; dotted tool names, hot-swapping a config mid-conversation, and the CLI validate command, all deferred on the Pipecat side; docs for other Pipecat areas touched by the same release; the async-tool result framing being fixed separately.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L1qgY9qoFGQUs2zbrVAWhA

[github-actions]

🔍 Mintlify preview for this branch: https://daily-docs-flows-declarative.mintlify.site