@absolutejs/voice 0.0.22-beta.121 → 0.0.22-beta.122

package/README.md

@@ -224,9 +224,9 @@ app.use(
 
 The suite rolls up session quality, scenario evals, fixture simulations, tool contracts, and outcome contracts into one pass/fail report. It is the code-owned equivalent of "test this voice flow before production" without requiring a hosted voice-agent dashboard.
 
-## Phone Voice Agent Path
+## Phone Voice Agent In 20 Minutes
 
-Use the telephony primitives when the agent needs to answer or place calls through your own carrier account:
+Use `createVoicePhoneAgent(...)` when the agent needs to answer or place calls through your own Twilio, Telnyx, or Plivo account. This is the self-hosted alternative to a hosted phone-agent dashboard: your app owns the carrier routes, stream URLs, webhooks, traces, readiness checks, and lifecycle outcomes.
 
 ```ts
 import {
@@ -242,6 +242,10 @@ const outcomePolicy = createVoiceTelephonyOutcomePolicy({
 app
 	.use(
 		createVoicePhoneAgent({
+			setup: {
+				path: '/api/voice/phone/setup',
+				title: 'Support Phone Agent'
+			},
 			matrix: {
 				path: '/api/carriers',
 				title: 'AbsoluteJS Voice Carrier Matrix'
@@ -274,7 +278,42 @@ app
 	);
 ```
 
-The wrapper mounts selected carrier routes and a readiness matrix. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
+The wrapper mounts selected carrier routes plus two proof surfaces:
+
+- `/api/voice/phone/setup`: one setup report with carrier URLs, smoke links, lifecycle stages, and readiness.
+- `/api/voice/phone/setup?format=html`: copy/paste setup page for carrier dashboards.
+- `/api/carriers`: carrier matrix JSON for Twilio, Telnyx, and Plivo.
+- `/api/carriers?format=html`: side-by-side carrier readiness matrix.
+
+The setup page tells you exactly what to copy into the carrier dashboard:
+
+- Twilio: set the phone number voice webhook/TwiML URL to the reported TwiML URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+- Telnyx: set the connection TeXML URL to the reported TeXML URL, set the status webhook to the reported webhook URL, and allow the reported `wss://` media stream.
+- Plivo: set the answer URL to the reported answer URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+
+Each configured carrier can also expose its own setup and smoke pages, for example:
+
+- `/api/voice/twilio/setup?format=html`
+- `/api/voice/twilio/smoke?format=html`
+- `/api/voice/telnyx/setup?format=html`
+- `/api/voice/telnyx/smoke?format=html`
+- `/api/voice/plivo/setup?format=html`
+- `/api/voice/plivo/smoke?format=html`
+
+The phone-agent report normalizes the lifecycle schema across carriers:
+
+- `ringing`
+- `answered`
+- `media-started`
+- `transcript`
+- `assistant-response`
+- `transfer`
+- `voicemail`
+- `no-answer`
+- `completed`
+- `failed`
+
+That is the important Vapi/Retell/Bland gap this primitive closes: a team can mount one phone-agent entrypoint, bring its own carrier account, verify readiness before live calls, and keep call traces and lifecycle outcomes inside its own AbsoluteJS app. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
 
 ## App Kit And Status Widgets
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.121",
+	"version": "0.0.22-beta.122",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",