docs(vapi): document managed ingestion and correct span shape - #1090

Release hold

Do not merge or publish this guide yet. The Vapi polling credential prerequisite is now repaired in future-agi/future-agi#3704 at bd9369a95546a8bbc5f6df722f31c395bd2d098f, but that product PR still needs normal review, Nikhil’s merge and deployment. A pushed product fix is not a deployed fix; keep this guide held through those steps.

The repair uses the canonical active/latest version credential reader, preserves encrypted legacy fallback, and fails incomplete configuration before advancing the polling watermark. Regression tests exercise real hosted API creation, encrypted PostgreSQL persistence, credential change/preflight/default activation and polling, for both null and stale legacy columns. With the unchanged backend, 13 of 14 new cases fail; with the repair, the expanded 407-test backend suite passes. All external provider/preflight/workflow boundaries are inert, and no live Vapi call or full browser E2E is claimed. Evidence is under /Volumes/nik-ext-1/tmp/opus-resume-20261101/work/rest-vapi-agnostic/refix-2/evidence/: base-regression-proof.log, tests-final.log, and run-tests.sh.

This docs head is unchanged in the product-fix round. Its 26 integration tests, link audit and Astro/Pagefind build passed again in the required sandbox. No customer-facing QA notes were added.

Summary

• Give Vapi its own managed-ingestion setup page and link it directly from the integration directory/sidebar.
• Replace retired Agent Definition navigation with Agents > Create Agents > Connect agents > Hosted platform > Voice > Vapi, including Run preflight and Build environment.
• Explain the connected agent's Definition > Observability switch, automatic saving, permissions and refusal behavior.
• Document credential rotation through the connected agent's Environments tab, environment Overview > Manage versions > Credentials > Change values, and the VAPI_API_KEY version check/default transition. Do not invent an editor on the read-only Definition tab.
• Preserve private-key/recording guidance and the distinction between managed conversation messages and instrumented STT/LLM/TTS child spans. No copied tracing helper or SDK installation.

Verification

• Reproduced retired list redirects for both organization modes and legacy create/edit 404s for restricted organizations using the unmodified production route registry and real React Router matching.
• Four Vapi documentation tests failed before the repair; all six Vapi tests and the complete 26-test integration suite pass afterward.
• Current connected-agent, environment-builder and environment-detail routes match for both organization modes. Separately checked the displayed controls and component wiring against product dev 42f1fe1f098fb5dec2081a242f532b22df26bf52.
• Astro/Pagefind build passes. Link audit reports zero broken navigation/content links; 28 existing orphan warnings remain.
• Both changed guides render in isolated desktop Chrome with external requests blocked, no page errors or overflow; the updated Vapi screenshot was visually inspected.
• All offline checks ran under the outbound-network-denied sandbox. No live Vapi call, Cloud/customer credentials, full product E2E, or real product screenshot was used or claimed.
• This is a docs-only hosted integration change: SDK floor/latest matrices, package release manifests and registry publishing are not applicable.

Merged current origin/main normally, without force-pushing. Keep the release hold above until the product polling prerequisite is reviewed, merged by Nikhil and deployed.

🤖 Generated with Claude Code