@guidify-ai/vapi-studio 0.1.0

package/docs/best-practices/identity-and-pii.md

@@ -0,0 +1,66 @@
+# Identity and PII
+
+Collecting caller identity without poisoning memory or stacking CTAs.
+
+## Consent before destination
+
+SMS / form delivery is two turns when both are needed:
+
+1. **Consent** — “Is it okay if I text you a short form for your details?”
+2. **Destination** — calling-from suitable? **or** best mobile?
+
+Never ask consent and phone in one prompt. Decline → voice fallback path; do not re-ask consent after it is set for this Conversation.
+
+## Phone numbers (NA default)
+
+Unless the app explicitly supports other regions:
+
+- Store **exactly 10 digits**.
+- Strip leading country `1` when 11 digits.
+- If more than 10 digit characters appear (trailing ASR), take the **first 10**.
+- Fewer than 10 → fail and re-ask phone only.
+- Use a **short** listen timeout while collecting digits.
+- **Read-back confirm is mandatory** after spoken digits: “I heard 555-010-0999. Is that correct?” before SMS/form. Accepting calling-from ANI counts as confirm. Do not proceed on digits alone.
+- Incomplete ASR (fewer than 10 digits) → say you only caught N digits and ask again — not a generic “sorry, what’s the number?”
+- First ask for a missing field (e.g. mobile after consent) is a **gap fill**, not a re-ask — never preface with “I’m sorry, I didn’t quite get it.”
+
+## Names
+
+A person name is letters (and limited punctuation), not digits, not “hello”, not a full sentence. Reject and re-ask; never place digit strings into `firstName` / profile verify summaries (“I have 2 3 6 … on file”).
+
+**Spoken name frequency:** personal treatment is fine; saying the first name **more than once per turn** (or in consecutive sentences across `say` + `continueTo`) usually sounds wrong. At most one use per assistant turn unless there is an explicit reason (re-engage after silence, empathy, disambiguation). Prefer shared helpers and a “name already used this segment” flag — see [conversation-design.md](./conversation-design.md#personal-treatment-names).
+
+## Email
+
+Boxed helpers — prefer the dedicated path:
+
+```ts
+import {
+  EMAIL_EXTRACT_DESCRIPTION,
+  collectedEmail,
+  parseSpelledEmail,
+} from '@guidify-ai/vapi-studio/identity';
+// also: from '@guidify-ai/vapi-studio'
+```
+
+| Export | Role |
+| --- | --- |
+| `EMAIL_EXTRACT_DESCRIPTION` | `extract.fields[].description` so Brain GOT knows spelled ASR (`at` / `dot` / letter-by-letter) |
+| `collectedEmail(extracted, spoken)` | Prefer Brain extract, then spoken; `null` on fail |
+| `parseSpelledEmail(raw)` | Direct `name@domain` **or** spelled forms |
+
+Fail closed → re-ask the same CTA. Prefer a read-back confirm before sending mail (“I heard … Is that correct?”). Do not hardcode demo emails in production paths; PoC mocks belong behind clearly named constants and mock-only branches.
+
+## Forms
+
+- Deliver with `ctx.forms.open` (live Vapi) or `expose` (Studio-friendly blocking) + a dispose adapter that makes a fillable surface available (Studio modal, **first-party HTML** at `/forms/:exposeId`, or SMS link).
+- Field specs are JSON (`FormFieldSpec`); HTML is rendered from that JSON (`renderFormHtml`), not hand-written per form.
+- Submit must call `FormsService.submit(exposeId, values)` so the open path can `claimSubmitted()` (or blocking `expose` resumes).
+- **Local PoC without SMS:** open `/forms/inbox` on this machine — it lists exposed / unsubmitted forms; Open → fill → Submit unblocks the waiting bot.
+- **Caller never got the text / link:** while the form is still open, listen for “I didn’t get it / no text / didn’t receive the link.” Then **one CTA**: resend via `ctx.forms.resend()` and ask **“Did you get it this time?”** — do not also ask them to fill in the same turn. On yes → next turn asks them to open and fill. Cap resends (e.g. 2) then voice fallback. Never stack “resent” + “fill it out” + “still waiting” in one listen.
+- Form deliver/fill failure → **one CTA**: “OK to finish by voice?” then collect fields. Never stack failure notice + first-name ask in one listen.
+- After submit, voice-confirm received values when the channel is unreliable; do not treat unconfirmed ASR as identity.
+
+## Profile verify
+
+Only when CRM hydrated a **returning** caller (`returningCaller === true`, gated by `recognizeReturningCaller`). Never say “on file” for PII collected earlier in **this** Conversation. If recognition FF is off, treat every call as first-time for verify UX.

package/docs/best-practices/nodes-and-listens.md

@@ -0,0 +1,116 @@
+# Nodes and listens
+
+How to structure Vapi Studio Nodes so agents and humans can keep flows maintainable.
+
+## Start → Greeting
+
+Happy-path shape (how `/flow` should read, and how runtime should feel):
+
+```text
+Start  →  Greeting (flow.start)  →  …
+```
+
+| Step | What it is | Runtime |
+| --- | --- | --- |
+| **Start** | Call / bootstrap + inject bag + near-zero prep | `ConversationEntryPoint.createVariables` / `beforeEach` — company, email, name from LP; phone from caller; optional JWT/API warm. **Must not block first speech** (target < 1.5s to first SSE). Not a spoken Node; do not burn a Supervisor turn on silence. |
+| **Greeting** | First real speak | `flow.start` Node — opening turn only (no Brain scan). Then the product DAG. |
+
+**Do not** add Conversation-start or assistant-name bookends before Greeting on single-flow diagrams — Start is the entry. Squad/workflow lanes may still show per-module `__start` labels for handoff identity.
+
+## Node = one job
+
+Each Node should own a small slice: one ask, one verification, one side effect, or one lane step. If you need two sequential CTAs, use two Nodes (or `output.continueTo({ nodeId })`) — see [conversation-design.md](./conversation-design.md).
+
+## Prefer `before()` / `after()` for async work
+
+Do **not** overload `run()` with auth, CRM lookups, JWT warmups, or post-speak teardown. `run()` owns **speech + one terminal output** (`sayAndListen` / `continueTo` / `endCall` / …). Keep side effects on the lifecycle hooks:
+
+| Hook | Role | Async guidance |
+| --- | --- | --- |
+| **`before(ctx)`** | CAN gate + prepare | Authorize (`return false` to reject). **Prep / warm** integrations here. Prefer **spawn without awaiting** when the token is for *later* Nodes (do not block first SSE — target < 1.5s). `await` only when the gate itself needs the result. |
+| **`listen(ctx)`** | Next listen binding | Register intentions / extract **before** speech; no I/O. |
+| **`run(ctx)`** | Speak + terminal action | Copy and routing only. Do not nest “fetch then greet” unless the speak **cannot** proceed without the result. |
+| **`after(ctx, result)`** | Teardown | Fire-and-forget analytics stamps that are not on the critical path, release handles, log completion. Must not speak. |
+| **`catch(ctx, error)`** | Recovery | Only when overridden. |
+
+Detached promises from `before()` should land in a Nest service / `Map<conversationId, Promise<…>>` (or similar), not assume late `ctx.memory` writes persist after the turn. Later Nodes `await` that shared promise when they need the value.
+
+## `listen()` must match the ask
+
+Whatever you just asked for, `listen()` should advertise:
+
+- Intention names + boosts for that answer class
+- `hints` for the Brain (short, operational)
+- `extract` fields with **constraint-aware** `description`s when collecting data
+- `resolveIntention` for cheap local matches (skip Brain when obvious) — include short answers like “new one” / “yes” / “ASAP” when the ask is constrained
+- **Open-ended discovery:** prefer `INTENTION_CASCADE_PHASE.Scan` for the catch-all answer intention (so Brain can classify short/ambiguous turns). Use Match only for clear proceed phrases; keep FAQ as Force. `resolveIntention` should skip Brain for long substantive answers (≥ ~12 chars) and re-ask soft affirmatives locally — do **not** Match every ≥4-char utterance (that starves Scan)
+- **Multi-choice soft affirmatives** (“yeah, why not”, bare “sure”) that do **not** name an option → re-ask which lane locally; never leave that to Brain/unknown ([conversation-design.md](./conversation-design.md#do-not-auto-pick-lanes))
+- After a resolved binary fork (existing vs new, yes/no), **stamp memory** so the next menu advances; otherwise unknown recovery and re-prompts keep re-asking the same choice
+- Unknown portal: Supervisor re-tries the **origin listen** on the next utterance before unknown’s own candidates — keep origin `resolveIntention` strong so restatements land on this turn
+- `timeoutSeconds` when the answer type needs a non-default window
+
+Do not leave a broad “collect name” listen active while you are asking for SMS consent.
+
+## Extracts teach the Brain
+
+`description` is part of the product. Spell the rule:
+
+> North American mobile: exactly 10 digits. Prefer the first 10 digit characters; ignore trailing words. Fail if fewer than 10.
+
+Local parsers and GOT must agree. Prefer framework boxed helpers from `@guidify-ai/vapi-studio/identity` (`collectedEmail`, `EMAIL_EXTRACT_DESCRIPTION`); app helpers (`collectedPhone`, `collectedPersonName`, …) for the rest — called from `onExtracted`.
+
+## Memory writes are guarded
+
+Never write PII from raw `userText` without a validator (`looksLikePersonName`, phone normalizer, email parser). Fail closed → re-ask the same CTA.
+
+**Never speak untrusted input:** do not `say(ctx.userText)`, Brain `reason`, or judge `reasoning` to the caller. Off-topic / injection-shaped speech → `studio.isUnknownTransition` or structured recovery — see [brain-and-prompt-injection.md](./brain-and-prompt-injection.md).
+
+**Never speak implementation labels:** node ids, class names, intention/transition names, event types, or graph state (“we were at X”) — see [conversation-design.md](./conversation-design.md) § Human-like UX. `listen()` hints/notes are Brain-only, not TTS.
+
+## Flow jumps
+
+| Action | When |
+| --- | --- |
+| `sayAndListen` | Stay on this Node; wait for the next user turn |
+| `continueTo({ nodeId })` | Same Conversation, same flow, different Node (often same turn entry speak) — **silent** unless the destination needs a new product CTA; no filler restating the last beat ([conversation-design.md](./conversation-design.md#copy-hygiene)) |
+| `handoff({ to })` | Workflow module switch (Squad / multi-assistant). Same silent-handoff rule. Only when a workflow is loaded |
+
+Keep live PoCs on one assistant + `continueTo` unless you are deliberately testing Squad.
+
+## Portals stay portals
+
+Transfer, pause, mad, unknown, still-there, goodbye remain high-priority portals. Happy-path Nodes must not reimplement them. Unknown recovery copy can be shared with the unknown portal so menus stay consistent.
+
+### Mad: one re-engage, then human (hard rule)
+
+Do **not** keep reasoning with, apologizing to, or negotiating angry callers across multiple turns. Mad people escalate; a bot that stays in de-escalation loops wastes the call and makes things worse.
+
+| Policy | Detail |
+| --- | --- |
+| **First mad hit** | One short re-engage (acknowledge + invite them to continue productively), then listen |
+| **Second mad hit** (still heated) | **Transfer to a human** (or after-hours block) — no third apology loop |
+| **Calm continue / goodbye** | May leave the portal without transferring |
+| **Do not** | Invent long empathy scripts, argue, or keep `sayAndListen` de-escalation forever |
+
+Framework note: mad is sticky (other portals suppressed while active) so the next utterance stays on the mad listen — that is for routing control, not an excuse to chat with anger. App mad Nodes must enforce the one-re-engage → transfer policy.
+
+### Portal re-engage must end with one CTA (hard rule)
+
+Any portal turn that **defers** the caller’s ask (transfer re-engage, mad first apology, after-hours block) must still obey **one CTA per turn**. Do not leave them on a dead-end statement.
+
+| Bad | Good |
+| --- | --- |
+| “I understand you want a human, but I can resolve it for you.” *(no ask)* | “I can often take care of this without a transfer — **how can I help you?** Or say you'd still like a person.” |
+| “I'm sorry you're frustrated.” *(stops)* | “I'm sorry you're dealing with this — **tell me what's going on**, and I'll help.” |
+
+Listen for that turn must accept: insist again (transfer/mad), calm continue, **or** a product need if you offered help.
+
+## Flow YAML is paths (+ optional condition transitions)
+
+`flow.yaml` lists node ids, class names, intentions, portal flags, priority, and optional **`transitions`** (pure `when` gates → `to` node, with `force` to skip Brain). Copy and extract schemas live in Node source — not in YAML, not in app README northern stars.
+
+**Prefer code intentions** (`INTENTION_CASCADE_PHASE.Force` \| `.Match` \| `.Scan`) when a gate needs memory/history/regex freedom — register via `VapiStudioModule.forRoot({ intentions })`. YAML transitions stay useful for diagram edges; code force intentions run first in the cascade.
+
+Use **dedicated Nodes** for identity gap-fill (consent, phone, name). Declare the same gates as `transitions` and/or force intentions when you need the graph to show *why* the bot must leave a Node — duplicating a `continueTo` is fine.
+
+`continueTo({ text })` is spoken on the wire — do not repeat copy (especially the caller’s name) that a prior `say` in the same pass already delivered. See [conversation-design.md](./conversation-design.md#personal-treatment-names).

package/docs/best-practices/ui-and-api-identity.md

@@ -0,0 +1,51 @@
+# UI and API identity
+
+Hard rules for Studio UI ↔ Nest APIs and durable records. Applies to framework Studio SPA, app-served JSON, and any new FE surface.
+
+## Rules (summary)
+
+1. **External comms use UUID only** — paths, query params, request/response bodies, links, and client state identify records by `uuid`. Never send or accept numeric/`bigint` `id` from the FE (or any external client).
+2. **BE stores `id` + `uuid`** — every durable entity has an internal integer/`bigint` primary key (`id`) for joins, filters, sorts, and indexes, and a unique `uuid` for all external identity. Services may use `id` internally; repositories that face HTTP resolve by `uuid`.
+3. **Every exposed entity has a human `label`** — API DTOs return `label` so the UI can title rows, breadcrumbs, and headings **without** printing UUIDs. Prefer `label` in the UI; use `uuid` only as the opaque key (URL segment, React key, fetch param).
+
+## Field contract
+
+| Layer | Internal PK | External id | Human display |
+| --- | --- | --- | --- |
+| DB / TypeORM | `id` (`bigint` / serial) | `uuid` (unique, indexed) | `label` (varchar) and/or derived DTO `label` |
+| HTTP JSON | **omit** | `uuid` | `label` (required on list + detail) |
+| Studio UI | never | URL + API only | always show `label` |
+
+Do **not** name the external field `id` in new APIs. Use `uuid` so clients never confuse it with the internal key.
+
+```json
+{
+  "uuid": "4a13e554-972b-4713-b208-15b71bff0493",
+  "label": "Sample Studio · ACTIVE · Sep 6, 1:30 PM",
+  "status": "ACTIVE"
+}
+```
+
+```http
+GET /conversations/api/:uuid
+```
+
+Not: `GET /conversations/api/42` or `{ "id": 42 }`.
+
+## Labels
+
+- **Stable enough to read** — short title a human understands (project name, caller display, “Studio call · ended”, channel + time).
+- **Not a dump of the UUID** — never use the raw uuid string as `label`.
+- **Computed OK** — if there is no stored column, the service may build `label` when mapping to the DTO (must still always be present on FE responses).
+- **UI rule** — list rows, page titles, and toasts use `label`; monospace UUID only in operator “copy id” / debug affordances if needed.
+
+## Backend practice
+
+- Joins, `ORDER BY`, range filters, analytics aggregations → `id` (and indexed columns).
+- `findByUuid` / route params → `uuid`.
+- Never leak `id` in JSON, logs meant for operators who share URLs, or Vapi-facing payloads that the FE might echo.
+- Nested resources: parent and child both identified by `uuid` in URLs (`/…/:conversationUuid/events/:eventUuid`).
+
+## Migration note
+
+Older tables may still use UUID as `@PrimaryGeneratedColumn('uuid')` named `id`. Treat that as transitional: new entities follow `id` + `uuid` + `label`; when touching persistence for an existing entity, migrate toward this shape and rename API fields to `uuid` + `label` in the same change.

package/docs/building-apps/creating-an-app.md

@@ -0,0 +1,59 @@
+# Creating an application
+
+Start from the public starter **[vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project)**. That repo is the Nest shell for your bot: `flow.yaml`, Vapi routes, Docker, agent rules. This package (`@guidify-ai/vapi-studio`) is the framework it depends on — not an app template.
+
+Do not put production secrets or customer flows in the framework repository.
+
+## 1. Clone the starter
+
+```bash
+git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
+cd my-bot
+cp .env.example .env
+# Edit PROJECT_NAME=…  (PROJECT_SLUG optional — defaults from the name)
+yarn install
+yarn start   # Docker Postgres + app + ngrok → prints Vapi URLs
+```
+
+`yarn install` pulls `@guidify-ai/vapi-studio@0.1.0` and stamps Cursor/Claude rules + `AGENTS.md`. Postinstall syncs `config/project.identity.json` from `PROJECT_NAME` / `PROJECT_SLUG` (name + slug only).
+
+### Live voice prerequisites
+
+| Need | Detail |
+| --- | --- |
+| **Vapi** | Client has Vapi org access. `VAPI_API_KEY=` in `.env.example` is **required** (leave empty in the example; fill in `.env`). **Vapi is paid** — budget for Vapi usage/plan charges as well as Twilio. |
+| **Twilio only (for now)** | Vapi supports other carriers; this stack currently assumes **Twilio**. Put `TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN` / `TWILIO_FROM_NUMBER` in the app `.env`. |
+| **Trust Hub / +1** | Twilio Trust Hub + voice geo must allow outbound to **+1**. Trial / blocked geo → `Account not allowed to call +1…`. |
+| **Balance** | Recommend ~**$30** with auto-recharge to $30 when balance hits ~$10. |
+| **Same account** | `VAPI_PHONE_NUMBER_ID` must be a number imported in Vapi from **that** Twilio account. |
+
+## 2. Wire Vapi
+
+Paste the printed URLs into your Vapi assistant:
+
+| Setting | Endpoint |
+| --- | --- |
+| **Webhook** | `{PUBLIC_BASE_URL}/vapi/webhook` |
+| **Custom LLM** | `{PUBLIC_BASE_URL}/vapi/chat/completions` |
+
+Each starter fork is its own deploy (own host / port / ngrok URL). Paths are host-scoped — no project UUID in the URL.
+
+## 3. Build your conversation
+
+1. Add `@Injectable()` classes extending `AgentNode<YourSchema>` under `src/conversation/`
+2. Register them in `VapiStudioModule.forRoot({ nodes: [...] })` in `app.module.ts`
+3. Reference them from `config/flow.yaml`
+4. Grow `src/vapi/` as needed (webhook strategies, tools) — see the [showcase](https://github.com/guidify-ai/vapi-studio-landing-page-sample-model) for a full Planner PoC
+
+Operator UI (`/flow`, `/conversations`) comes from the framework SPA mounted by the starter.
+
+## 4. Keep going
+
+- [Vapi adapter](../guide/vapi-adapter.md) — Custom LLM SSE + webhooks
+- [Module setup](../guide/module-setup.md) — `VapiStudioModule.forRoot`
+- [Best practices](../best-practices/README.md) — conversation design doctrine
+- [Runtime API](../reference/runtime-api.md) — shipped contracts
+
+## Framework contributors
+
+Clone [vapi-studio](https://github.com/guidify-ai/vapi-studio) only when changing the library itself (`yarn build`, `yarn test`). Apps always start from [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project).

package/docs/building-apps/example-apps.md

@@ -0,0 +1,23 @@
+# Example applications
+
+## Starter (start here)
+
+**[vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project)** — blank Nest shell for a new bot.
+
+```bash
+git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
+cd my-bot && cp .env.example .env
+# Edit PROJECT_NAME=…
+yarn install && yarn start
+```
+
+Surface after `yarn start`:
+
+- Operator SPA: `/flow`, `/conversations`
+- Ingress: `/vapi/webhook`, `/vapi/chat/completions` (host-scoped)
+
+Step-by-step: [Creating an app](./creating-an-app.md).
+
+## Showcase (reference implementation)
+
+**[vapi-studio-landing-page-sample-model](https://github.com/guidify-ai/vapi-studio-landing-page-sample-model)** — Planner LLM demo (not a blank starter). Depends on `@guidify-ai/vapi-studio@0.1.0` (or `file:../vapi-studio` while developing the next package version). Use it to see richer Vapi strategies, funnels, and multi-node flows.

package/docs/building-apps/overview.md

@@ -0,0 +1,27 @@
+# Building applications — overview
+
+**[@guidify-ai/vapi-studio](https://www.npmjs.com/package/@guidify-ai/vapi-studio)** is an npm library. Your bot is a NestJS app that depends on it.
+
+**Start every new bot by cloning [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project)** — then rename, set `PROJECT_NAME`, and extend nodes / `flow.yaml`.
+
+```text
+my-bot/                         ← clone of vapi-studio-project
+├── package.json                ← "@guidify-ai/vapi-studio": "0.1.0"
+├── config/
+│   ├── project.identity.json   ← name + slug (from .env)
+│   └── flow.yaml
+├── src/
+│   ├── conversation/           ← your agent steps
+│   └── vapi/                   ← /vapi/webhook + /vapi/chat/completions
+└── docker-compose.yaml
+```
+
+| Repo | Role |
+| --- | --- |
+| [vapi-studio](https://github.com/guidify-ai/vapi-studio) | Framework → npm `@guidify-ai/vapi-studio` |
+| [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project) | **Starter** — fork this to ship a bot |
+| [vapi-studio-landing-page-sample-model](https://github.com/guidify-ai/vapi-studio-landing-page-sample-model) | Showcase (Planner LLM) — study patterns, not a blank template |
+
+Do not add customer-specific agent steps under the framework `src/` — only in your starter fork.
+
+[Creating an app](./creating-an-app.md) · [Example apps](./example-apps.md)

package/docs/getting-started/installation.md

@@ -0,0 +1,52 @@
+# Installation
+
+## New bot (recommended)
+
+You do **not** install the framework into an empty folder by hand. Clone the starter — it already depends on the package:
+
+```bash
+git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
+cd my-bot
+cp .env.example .env
+yarn install   # installs @guidify-ai/vapi-studio@0.1.0 + stamps agent rules
+yarn start
+```
+
+Starter: [guidify-ai/vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project)  
+Package: [npm `@guidify-ai/vapi-studio`](https://www.npmjs.com/package/@guidify-ai/vapi-studio)
+
+Vapi Studio apps are **self-hosted** and **Dockerized**. There is no Guidify-hosted runtime. Vapi is the cloud voice channel; your containers serve Custom LLM + webhook.
+
+## Requirements
+
+- **Node.js 22+**
+- **Yarn 1.x** or npm
+- **Docker** + Compose
+- **[ngrok](https://ngrok.com/download)** for local HTTPS to Vapi
+- A **Vapi** account
+
+On install, the package **postinstall** stamps agent rules (`AGENTS.md`, `.cursor/rules/…`) into the starter when present.
+
+## What is published (and what is not)
+
+The npm tarball includes **`dist/`**, **`docs/`**, **`agent/`**, **`scripts/`**, **`LICENSE`**, **`README.md`**. It does **not** include `.env`, secrets, or application bots.
+
+## Contribute to the framework (optional)
+
+Only when changing the library itself:
+
+```bash
+git clone git@github.com:guidify-ai/vapi-studio.git
+cd vapi-studio
+yarn install
+yarn build
+yarn test
+```
+
+## Agent refs (manual)
+
+```bash
+INIT_CWD=$PWD node node_modules/@guidify-ai/vapi-studio/scripts/install-agent-refs.cjs
+```
+
+Next: [Quick start](./quick-start.md) · [Creating an app](../building-apps/creating-an-app.md)

package/docs/getting-started/introduction.md

@@ -0,0 +1,23 @@
+# Introduction
+
+**Vapi Studio** (`@guidify-ai/vapi-studio`) is a NestJS toolkit for **deterministic voice agents** on [Vapi](https://vapi.ai).
+
+Your bot is a **separate NestJS app**. Start from **[vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project)** — clone it, set `PROJECT_NAME`, then own nodes, `flow.yaml`, secrets, and Docker.
+
+## What you get
+
+- Typed agent steps (`AgentNode`), Supervisor routing, optional Brain at listen boundaries
+- Forms, tasks, event bus, Studio operator SPA assets
+- Docs and agent rules stamped into consumer apps on install
+
+## What you build
+
+A fork of [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project) that depends on `@guidify-ai/vapi-studio@0.1.0`, with Vapi Custom LLM + webhook at `/vapi/...` on your host.
+
+## What this is not
+
+- A no-code builder or open-ended LLM agent platform
+- A Guidify-hosted runtime (you self-host)
+- A monorepo of customer bots (each bot is its own starter fork)
+
+Next: [Installation](./installation.md) · [Quick start](./quick-start.md) · [Concepts](../guide/concepts.md)

package/docs/getting-started/quick-start.md

@@ -0,0 +1,23 @@
+# Quick start
+
+Clone the public starter, name the project, run it.
+
+```bash
+git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
+cd my-bot
+cp .env.example .env
+# Edit PROJECT_NAME=…  (PROJECT_SLUG optional)
+yarn install
+yarn start   # Docker + Postgres + ngrok → prints Vapi URLs
+```
+
+Paste into your Vapi assistant:
+
+| Setting | URL |
+| --- | --- |
+| Webhook | `{PUBLIC_BASE_URL}/vapi/webhook` |
+| Custom LLM | `{PUBLIC_BASE_URL}/vapi/chat/completions` |
+
+Then extend `src/conversation/` and `config/flow.yaml`. Full walkthrough: [Creating an app](../building-apps/creating-an-app.md).
+
+Framework contributors (changing the library, not starting a bot): clone [vapi-studio](https://github.com/guidify-ai/vapi-studio), `yarn build`, `yarn test` — see [Installation](./installation.md).

package/docs/guide/concepts.md

@@ -0,0 +1,103 @@
+# Concepts
+
+Mental model for Vapi Studio. API detail: [Runtime API](../reference/runtime-api.md).
+
+## Conversation
+
+A **Conversation** is one caller session:
+
+- **Framework-generated `conversationId`** — canonical id (never replace with Vapi call id)
+- **Variables** — seeded once at entry (channel, caller id, feature flags)
+- **Memory** — mutable working state for the call
+- **History** — turn log for Brain and forensics
+- **Postgres row** — durable lifecycle; in-memory `SupervisedConversation` for active calls
+
+## Turn lifecycle
+
+Each user utterance (or silence timeout) triggers the **Supervisor** routing cascade:
+
+```text
+1. Force intentions (code + YAML transitions)
+2. Condition transitions (memory expressions)
+3. Match intentions on current node
+4. Listen resolve (extract / resolveIntention — may skip Brain)
+5. Brain scan (portal + node intentions)
+6. Walk nodes (boot via before(), run)
+```
+
+On failure to route, the framework falls back to `studio.isUnknownTransition` rather than throwing.
+
+## Agent steps
+
+Agent steps are NestJS injectable classes extending `AgentNode`:
+
+```typescript
+export class AskNameNode extends AgentNode<MySchema> {
+  async before(ctx) { return true; }  // CAN gate
+  async listen(ctx) { /* register extract */ }
+  async run(ctx) {
+    return ctx.output.sayAndListen("What's your first name?", {
+      extract: { fields: [{ key: 'firstName', /* … */ }] },
+    });
+  }
+}
+```
+
+Declare methods in **runtime order**: `before` → `listen` → `run` → `after` → `catch`.
+
+Agent steps speak only through `ctx.output` — never Vapi JSON directly.
+
+## Flow YAML
+
+`config/flow.yaml` declares:
+
+- **start** node id
+- **nodes** — class binding, intentions, `portal`, `priority`, `terminal`
+- **transitions** — conditional jumps (`when`, `force`, `reason`)
+- **portals** — global interrupts (goodbye, transfer, still-there, mad)
+
+Lane changes inside one assistant use `ctx.output.continueTo({ nodeId })`.
+
+## Intentions
+
+Named signals routing the supervisor:
+
+- **Standard** — `studio.isGoodbye`, `studio.isTransferToHuman`, `studio.isStillThere`, …
+- **App** — `isAcceptedAppointment`, `isDidNotReceiveForm`, …
+- **Code intentions** — `CodeIntention` with `INTENTION_CASCADE_PHASE` (`Force` \| `Match` \| `Scan`; see [Runtime API](../reference/runtime-api.md))
+
+## Brain
+
+`BrainService` implements `scan` / `clarify` / `judge`. Model and confidence threshold are set in **`VapiStudioModule.forRoot({ brain })`** — not env vars.
+
+Live-call rules: no pre-scan listen-hold on ChatGPT path; scan abort ≤ 3s; target first speech < 1.5s.
+
+## Vapi integration
+
+Vapi Custom LLM and webhooks translate wire format ↔ Vapi Studio I/O.
+
+- **Live calls** — SSE streaming, tool calls for end/transfer/handoff
+- **Flow Studio** — HTTP text harness on the same supervisor (application feature for local dev)
+
+## Forms
+
+`ctx.forms.open()` (live Vapi) or `expose()` (blocking Studio) + a **dispose adapter** delivers fillable surfaces. Submit → `claimSubmitted()` or blocking resume.
+
+## Events
+
+Vapi Studio is **event-driven**. `EventService` emits `StudioEvent`s (`STUDIO_EVENTS` constants) onto the console, an in-process Node bus (`onStudioEvent`), and optional Nest `eventListeners`. Attach custom listeners for any logic you need — Guidify companion tools use the same hooks; OSS does not limit what you build there. Logs must explain **why** a turn routed. See [Events & logging](../reference/events-and-logging.md) · [Extending events](../guides/extending-events.md).
+
+## Conversation limits
+
+Every Conversation has always-on caps (`limits.maxTurns` / `limits.maxDurationMs`, defaults 40 / 20m). Fail-closed goodbye + `endCall` when exceeded — see [Runtime API](../reference/runtime-api.md) and [conversation design](../best-practices/conversation-design.md).
+
+## Resume & recovery (post-MVP)
+
+Framework ships optional helpers; **MVP apps start fresh each call** unless you explicitly opt in:
+
+- **Cross-call resume** — `ConversationResumeService` (same caller within ~10 minutes)
+- **Crash recovery** — `restoreAllActive()` on process boot (single-process; not multi-node failover)
+
+## Workflows (optional)
+
+Multi-assistant **Squad** handoffs via `workflow.yaml` — see [Workflow & Squad](./workflow-squad.md). Many apps use **one assistant** and `continueTo` lanes instead.

package/docs/guide/forms.md

@@ -0,0 +1,102 @@
+# Forms
+
+Structured collection outside the voice channel — SMS links, Studio modals, first-party HTML.
+
+## API surface (`ctx.forms`)
+
+| Method | Use when |
+| --- | --- |
+| `expose(spec)` | **Blocking** — holds the channel turn until submit (Flow Studio modal) |
+| `open(spec)` | **Non-blocking** — deliver + speak, finish SSE turn, wait for submit later (live Vapi) |
+| `resend()` | Caller did not receive SMS/link — re-run dispose on same `exposeId` |
+| `claimSubmitted()` | Take values after `open()` submit |
+| `hasPending()` | Open expose awaiting submit (ghosting must no-op) |
+| `hasUnclaimedSubmit()` | Submitted but not yet claimed |
+
+## Dispose adapter
+
+Apps provide `FormDisposeAdapter`:
+
+```typescript
+@Injectable()
+export class LinkFormDisposeAdapter implements FormDisposeAdapter {
+  readonly id = 'studio-first-party-html';
+  readonly branch = 'html_link';  // delivery lane for forensics
+
+  async dispose(payload: FormDisposePayload): Promise<void> {
+    // Publish URL, send SMS, open Studio modal…
+    forms.ack(payload.exposeId);
+  }
+}
+```
+
+`disposeContext` on expose is opaque app data (e.g. `contactPhone`, `channel`) stored for `resend()`.
+
+### Twilio SMS (prepared)
+
+Framework ships `TwilioSmsFormDisposeAdapter` (`branch: sms`). Wire it when you want SMS link delivery:
+
+```ts
+VapiStudioModule.forRoot({
+  formDisposeAdapter: TwilioSmsFormDisposeAdapter,
+  // …
+})
+```
+
+Reserved env (default **dry-run on** — no live Twilio calls until you opt in):
+
+| Variable | Purpose |
+| --- | --- |
+| `TWILIO_ACCOUNT_SID` | Account SID |
+| `TWILIO_AUTH_TOKEN` | Auth token |
+| `TWILIO_FROM_NUMBER` | E.164 from-number **or** |
+| `TWILIO_MESSAGING_SERVICE_SID` | Messaging Service SID |
+| `TWILIO_SMS_DRY_RUN` | Default `1` — still emits durable `OUTBOUND_NOTIFICATION` (`status: dry_run`) and ACKs without API. Set `0` for live send (requires peer package `twilio`) |
+
+Each send (dry-run or live) goes through `EventService.persist` as `OUTBOUND_NOTIFICATION` (in-process Node bus + Nest listeners). Failures emit `OUTBOUND_NOTIFICATION_ERROR`.
+
+`disposeContext` for this driver:
+
+```ts
+disposeContext: {
+  contactPhone: '5550100999', // or E.164 / `to` / `phone`
+  // formUrl optional — defaults to `{PUBLIC_BASE_URL}/forms/{exposeId}`
+  // body?: 'optional custom SMS text'
+}
+```
+
+Set `PUBLIC_BASE_URL` (ngrok/public HTTPS origin) so the texted link is reachable. Override with an explicit `formUrl` when the fill page lives elsewhere.
+
+## Events
+
+| Event | When |
+| --- | --- |
+| `FORM_SENDOUT` | Early — branch + delivery lane before ACK |
+| `FORM_EXPOSE` / `FORM_DELIVERED` | Adapter delivered |
+| `FORM_RESEND` / `FORM_RESENT` | Caller never got link |
+| `FORM_SUBMITTED` | Values received |
+| `FORM_DELIVER_TIMEOUT` / `FORM_FILLOUT_TIMEOUT` | Timeouts |
+
+## HTML helpers
+
+- `renderFormHtml(handle)` — JSON fields → fillable page
+- `renderFormThanksHtml()` / `renderFormGoneHtml()`
+
+Apps own HTTP routes (`GET/POST /forms/:exposeId`). Document routes in the application repository.
+
+## Timeouts
+
+- **ACK** — `STUDIO_FORM_ACK_MS` (default 15s) after dispose
+- **Fillout** — `filloutTimeoutMs` on expose spec (open path timer)
+
+## Doctrine
+
+- Form fail → **one CTA**: voice fallback
+- “Didn’t get text” → resend + “did you get it this time?” — not stacked with fill prompts
+
+Full rules: [Identity and PII](../best-practices/identity-and-pii.md)
+
+## Related
+
+- [Runtime API](../reference/runtime-api.md) — forms contracts
+- [Identity and PII](../best-practices/identity-and-pii.md)