@guidify-ai/vapi-studio 0.1.0

package/docs/guide/handbook.md

@@ -0,0 +1,21 @@
+# Handbook
+
+Runtime contracts moved out of the repository README.
+
+## Canonical sources
+
+| Layer | Path |
+| --- | --- |
+| **Entry index** | [README.md](../../README.md) — product intro, tools list, diagram, links |
+| **Runtime API** | [runtime-api.md](../reference/runtime-api.md) — shipped behavior (update with code) |
+| **Documentation site** | [docs/README.md](../README.md) |
+
+## Do not
+
+- Put application-specific agent steps or customer copy in framework docs
+- Import `@guidify-ai/vapi-studio/src/...` — use public `index.ts` only
+
+## Related
+
+- [Concepts](./concepts.md)
+- [Best practices](../best-practices/README.md)

package/docs/guide/introduction.md

@@ -0,0 +1,56 @@
+# Vapi Studio — Introduction
+
+**Vapi Studio** is Guidify AI's code-first framework for deterministic voice agents. It ships as `@guidify-ai/vapi-studio` in `vapi-studio/`.
+
+## What it is
+
+A NestJS module that provides:
+
+- **Supervised conversations** — one runtime per call, durable Postgres record
+- **Nodes** — `AgentNode` subclasses with `before` → `listen` → `run` → `after` → `catch`
+- **Flow YAML** — start node, intentions, portals, condition transitions
+- **Brain port** — mock, OpenAI, or your HTTP adapter for intention scan
+- **Output port** — `say`, `sayAndListen`, `endCall`, `transferToHuman`, `handoff`, `continueTo`, `invokeAdvertisedTool`, forms
+- **Vapi adapter** — OpenAI-compatible Custom LLM SSE + webhook helpers
+- **Events & logs** — call forensics (`ROUTE_DECISION`, form sendout, daily files)
+
+## What it is not
+
+- A no-code bot builder
+- A hosted SaaS
+- A place for customer-specific logic — that belongs in **your application** (separate from this package)
+
+## How apps use it
+
+```typescript
+VapiStudioModule.forRoot({
+  entryPoint: MyConversationEntry,
+  nodes: [
+    { className: 'AcknowledgeNode', useClass: AcknowledgeNode },
+    { className: 'GoodbyeNode', useClass: GoodbyeNode },
+  ],
+  intentions: [NeedSmsPhoneIntention],
+  brainAdapter: ChatGptBrainAdapter,
+  brain: {
+    model: 'gpt-4.1-mini',
+    confidenceThreshold: 0.4,
+  },
+  formDisposeAdapter: LinkFormDisposeAdapter,
+  eventListeners: [MyEventBuffer],
+})
+```
+
+Applications own `config/flow.yaml`, node classes, variables/memory types, channel wiring, and `.env`. The framework owns orchestration contracts.
+
+## Documentation map
+
+| Depth | Where |
+| --- | --- |
+| Concepts | [Concepts](./concepts.md) |
+| Wiring | [Module setup](./module-setup.md) |
+| Forms | [Forms](./forms.md) |
+| Vapi | [Vapi adapter](./vapi-adapter.md) |
+| Squads | [Workflow & Squad](./workflow-squad.md) |
+| Full API | [Runtime API](../reference/runtime-api.md) |
+| Conversation design | [Best practices](../best-practices/README.md) |
+| Example app | [Example apps](../building-apps/example-apps.md) (external repos) |

package/docs/guide/module-setup.md

@@ -0,0 +1,68 @@
+# Module setup
+
+The [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project) starter already depends on `@guidify-ai/vapi-studio` and wires `VapiStudioModule.forRoot`. Use this page when extending that module options block.
+
+## Dependency (already in the starter)
+
+```json
+{
+  "dependencies": {
+    "@guidify-ai/vapi-studio": "0.1.0"
+  }
+}
+```
+
+## `VapiStudioModule.forRoot` options
+
+| Option | Required | Purpose |
+| --- | --- | --- |
+| `nodes` | Yes | `{ className, useClass }[]` — every node in `flow.yaml` |
+| `entryPoint` | Yes | `ConversationEntryPoint` — seed variables, `beforeEach` / `afterEach` |
+| `brainAdapter` | Yes | `MockBrainAdapter`, `ChatGptBrainAdapter`, `ClaudeBrainAdapter`, `GeminiBrainAdapter`, `GrokBrainAdapter`, or custom |
+| `brain` | No | `{ model, confidenceThreshold }` for ChatGPT adapter |
+| `intentions` | No | `CodeIntention[]` providers (`INTENTION_CASCADE_PHASE`) |
+| `limits` | No | Always on: `{ maxTurns?, maxDurationMs?, endMessage? }` (defaults 40 / 20m; ceilings 150 / 60m) |
+| `eventListeners` | No | `StudioEventListener[]` |
+| `formDisposeAdapter` | No | Delivers forms (HTML link, Studio modal, Twilio SMS, …) |
+
+## Node registration pattern
+
+Every node class must be:
+
+1. A Nest `@Injectable()` extending `AgentNode<YourSchema>`
+2. Listed in `VapiStudioModule.forRoot({ nodes: [...] })`
+3. Referenced in `config/flow.yaml` by `className`
+
+## Conversation entry
+
+```typescript
+@Injectable()
+export class MyConversationEntry implements ConversationEntryPoint<MySchema> {
+  createVariables(ctx): MyVariables { /* channel, callerId, flags */ }
+  async beforeEach(ctx) { /* CRM hydrate, feature flags — not cross-call resume */ }
+  async afterEach(ctx) { /* optional */ }
+}
+```
+
+## Flow file location
+
+`FlowLoader` reads `config/flow.yaml` relative to `CONFIG_DIR` (default: app `config/` in Docker).
+
+## Agent scaffolding
+
+`yarn install` in an app runs postinstall:
+
+- `.cursor/rules/vapi-studio-best-practices.mdc`
+- `AGENTS.md` stamped block
+
+Manual refresh:
+
+```bash
+INIT_CWD=$PWD node node_modules/@guidify-ai/vapi-studio/scripts/install-agent-refs.cjs
+```
+
+## Related
+
+- [Concepts](./concepts.md)
+- [Runtime API](../reference/runtime-api.md)
+- [Creating an app](../building-apps/creating-an-app.md)

package/docs/guide/vapi-adapter.md

@@ -0,0 +1,70 @@
+# Vapi adapter
+
+How Vapi Studio compiles node output for Vapi Custom LLM and webhooks.
+
+## Endpoints (app-owned)
+
+Typical PoC routes:
+
+| Method | Path | Vapi assistant field |
+| --- | --- | --- |
+| `POST` | `/vapi/webhook` | **Webhook** — assistant-request, status-update, tool-calls |
+| `POST` | `/vapi/chat/completions` | **Conversation** (Custom LLM SSE, single assistant) |
+| `POST` | `/vapi/:moduleId/chat/completions` | **Conversation** per Squad module when workflow loaded |
+
+See [Creating an app](../building-apps/creating-an-app.md) for route patterns in your NestJS app.
+
+**Routing:** each starter fork is its own deploy (`PUBLIC_BASE_URL` / port). Paths are host-scoped — no project UUID segment. Vapi `assistantId` is forensics only — not used to pick the project.
+
+## Correlation
+
+- Vapi **call id** (`message.call.id`) maps to supervised runtime via `extractVapiCallId`
+- Framework **conversation id** is canonical — never replace with provider id
+- Lazy bootstrap: first Custom LLM POST may create runtime if webhook order differs
+
+## Custom LLM SSE contract
+
+1. Open SSE immediately (before Brain HTTP)
+2. Run supervisor turn
+3. Stream `say` chunks via `VapiSseCompiler`
+4. `sayAndListen` — speak then end turn as listening
+5. `endCall` / `transferToHuman` — OpenAI-compatible **tool calls** (names must match Vapi assistant tools)
+6. Duplicate/stale Custom LLM POSTs: replay on that connection — never empty dead air on live stream
+
+## Tool names (env)
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `VAPI_END_CALL_TOOL_NAME` | `end_call_tool` | Farewell `endCall` |
+| `VAPI_TRANSFER_CALL_TOOL_NAME` | `transfer_call` | Human transfer (`.env.example` snake_case; live may keep `transferCall`) |
+| `VAPI_HANDOFF_TOOL_NAME` | `handoff` | Squad module handoff |
+| `VAPI_TRANSFER_DESTINATION` | — | E.164 for transfer tool |
+
+Function names on the Vapi assistant **must match** these exactly.
+
+## Webhook strategies (PoC)
+
+| `message.type` | Typical behavior |
+| --- | --- |
+| `assistant-request` | Bootstrap + return `assistantId` or transient assistant config |
+| `call.started` / `assistant.started` | Bootstrap (saved-assistant path) |
+| `status-update` | Bootstrap on `in-progress`; finalize on `ended` |
+| `tool-calls` | Still-there portal tool → StillThere portal |
+| `user-interrupted` | Record interrupt |
+
+Guard: reject messages missing `message.call.id` → `400`.
+
+## Channel tools
+
+`ctx.tools` — tools advertised on this Custom LLM request  
+`ctx.toolResults()` — results from `role: tool` messages (re-entry after tool execution)
+
+## Operator setup
+
+Full dashboard checklist: implement in **your application** — see [Creating an app](../building-apps/creating-an-app.md).
+
+## Related
+
+- [Runtime API](../reference/runtime-api.md)
+- [Workflow & Squad](./workflow-squad.md)
+- [Creating an app](../building-apps/creating-an-app.md)

package/docs/guide/workflow-squad.md

@@ -0,0 +1,59 @@
+# Workflow & Squad
+
+Optional multi-assistant deployments. Many apps use **one assistant** and `continueTo` instead.
+
+## When to use
+
+| Pattern | Use |
+| --- | --- |
+| `continueTo({ nodeId })` | Same assistant, same Conversation — lane jumps |
+| `handoff({ moduleId })` | Vapi Squad — switch assistant, shared workflow memory |
+
+## `workflow.yaml`
+
+```yaml
+version: 1
+workflow:
+  id: my-workflow
+  entryModule: router
+modules:
+  router:
+    assistantName: MyRouter
+    kind: studio
+    flowFile: modules/router.flow.yaml
+    entryNode: routerTriage
+  identity:
+    assistantName: MyIdentity
+    kind: studio
+    flowFile: modules/identity.flow.yaml
+```
+
+- `WorkflowLoader` resolves module id ↔ Vapi `assistantName`
+- `WorkflowHandoffService` enriches handoff actions, checkpoints, emits `WORKFLOW_HANDOFF`
+- Handoff does **not** finalize the Conversation
+
+## URLs
+
+- `POST /vapi/:moduleId/chat/completions`
+- Header `X-Vapi-Studio-Module` also accepted
+
+## Vapi handoff tool
+
+SSE must call the handoff function with **`destination` as a string** (Squad member name), e.g.:
+
+```json
+{ "destination": "MyIdentity" }
+```
+
+Not `{ type, assistantName }` objects — that is assistant config, not tool-call args.
+
+## Examples on disk (not loaded by default)
+
+Ship example configs in your app repo (e.g. `config/workflow.squad.example.yaml`, `config/vapi-squad.example.json`).
+
+Copy to `workflow.yaml` only when deliberately enabling Squad.
+
+## Related
+
+- [Runtime API](../reference/runtime-api.md) — workflow / handoff
+- [Example apps](../building-apps/example-apps.md) — single-assistant vs squad patterns

package/docs/guides/agents.md

@@ -0,0 +1,85 @@
+# Agents & coding CLIs
+
+Guidify AI is built to be **agent-friendly**: one handbook, stamped refs, and always-on rules for Cursor and Claude Code.
+
+## Shared handbook
+
+| Resource | Purpose |
+| --- | --- |
+| [`agent/AGENTS.md`](../../agent/AGENTS.md) | Canonical doctrine (tool-agnostic) |
+| [`docs/best-practices/README.md`](../best-practices/README.md) | Which doctrine guide to open |
+| App `AGENTS.md` | Stamped block from package postinstall |
+
+Claude Code does **not** auto-read `AGENTS.md`. Keep the handbook under `agent/` (`AGENTS.md` + `CLAUDE.md`); put a one-line root `CLAUDE.md` that `@agent/CLAUDE.md` so Claude Code discovers it (Anthropic’s documented pattern).
+
+This framework package does **not** keep always-on rules under `.cursor/` or `.claude/` in-repo. Edit templates under `agent/`; postinstall copies them into **consumer apps**.
+
+## Cursor
+
+| Resource | Purpose |
+| --- | --- |
+| `agent/cursor/*.mdc` | Templates copied into app `.cursor/rules/` |
+| App `.cursor/rules/vapi-studio-best-practices.mdc` | Always-on conversation rules |
+| App `.cursor/rules/ui-and-api-identity.mdc` | UUID / label identity |
+
+## Claude Code CLI
+
+| Resource | Purpose |
+| --- | --- |
+| Repo [`agent/CLAUDE.md`](../../agent/CLAUDE.md) | Framework Claude notes (`@AGENTS.md`); root `CLAUDE.md` is discovery-only |
+| `agent/claude/rules/*.md` | Templates copied into **app** `.claude/rules/` on postinstall |
+| App `.claude/rules/vapi-studio-best-practices.md` | Always-on conversation rules |
+| App `.claude/rules/ui-and-api-identity.md` | UUID / label identity |
+| App `CLAUDE.md` | Stamped import of package `agent/AGENTS.md` |
+
+| Cursor template (`agent/cursor/`) | Claude template (`agent/claude/rules/`) |
+| --- | --- |
+| `vapi-studio-best-practices.mdc` | `vapi-studio-best-practices.md` |
+| `ui-and-api-identity.mdc` | `ui-and-api-identity.md` |
+
+See [Node conventions](./node-conventions.md) for agent-step naming and lifecycle order (doctrine in [nodes-and-listens.md](../best-practices/nodes-and-listens.md)).
+
+## Recommended workflow
+
+1. Read app **northern stars** (app repo `README.md`).
+2. Read `agent/AGENTS.md` / `agent/CLAUDE.md` (app: stamped `AGENTS.md` / `CLAUDE.md`).
+3. Open matching [best-practice guide](../best-practices/README.md).
+4. Framework changes → [Runtime API](../reference/runtime-api.md) first.
+5. Update docs in the **same PR** as behavior.
+
+## Decision tree: which guide?
+
+| Changing… | Read |
+| --- | --- |
+| Bot copy / CTA | conversation-design.md |
+| Soft affirmatives / silent handoffs / lane choice | conversation-design.md (+ nodes-and-listens.md) |
+| Mad callers (one re-engage → human) | nodes-and-listens.md · conversation-design.md |
+| New agent step / listen / extract | nodes-and-listens.md |
+| Phone, email, forms | identity-and-pii.md |
+| Studio FE / Nest DTO identity | ui-and-api-identity.md |
+| Analytics funnels / tags | debugging-and-observability.md · events-and-logging.md |
+| Logs / events | debugging-and-observability.md |
+| Limits / public API / env | [Runtime API](../reference/runtime-api.md) |
+| README placement | documentation-layers.md |
+
+## Postinstall
+
+```bash
+INIT_CWD=$PWD node node_modules/@guidify-ai/vapi-studio/scripts/install-agent-refs.cjs
+```
+
+Refreshes **in the consumer app**:
+
+- `.cursor/rules/vapi-studio-best-practices.mdc` + `ui-and-api-identity.mdc`
+- `.claude/rules/vapi-studio-best-practices.md` + `ui-and-api-identity.md`
+- stamped blocks in app `AGENTS.md` and `CLAUDE.md`
+
+Sources: `agent/cursor/` and `agent/claude/rules/` inside the package. Does not wipe custom sections outside the stamped markers.
+
+## SpecKit
+
+Greenfield features: [SpecKit guide](./speckit.md) (`.specify/` in this repo).
+
+## Related
+
+- [Documentation layers](./documentation.md)

package/docs/guides/docker-compose.events.stub.yaml

@@ -0,0 +1,27 @@
+# Optional compose fragment — Redis + a consumer process only.
+# Use the app's existing `postgres` service; create a second database on it
+# instead of a second Postgres container. Wire your own consumer image/env.
+#
+#   EVENT_STORE_DATABASE_URL=postgres://studio:studio@postgres:5432/app_events
+
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "${STUDIO_EVENTS_REDIS_HOST_PORT:-16379}:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+
+  event-consumer:
+    image: ${STUDIO_EVENT_CONSUMER_IMAGE:-studio-event-consumer:local}
+    environment:
+      DATABASE_URL: ${EVENT_STORE_DATABASE_URL:-postgres://studio:studio@postgres:5432/app_events}
+      STUDIO_EVENTS_REDIS_URL: ${STUDIO_EVENTS_REDIS_URL:-redis://redis:6379}
+      STUDIO_EVENTS_REDIS_STREAM: ${STUDIO_EVENTS_REDIS_STREAM:-studio:events}
+    depends_on:
+      redis:
+        condition: service_healthy
+    restart: unless-stopped

package/docs/guides/documentation.md

@@ -0,0 +1,13 @@
+# Documentation map
+
+| Layer | Location | Purpose |
+| --- | --- | --- |
+| **Package README** | `README.md` | Install + product framing |
+| **Doc site** | `docs/README.md` | Navigation |
+| **Runtime handbook** | `docs/reference/runtime-api.md` | Shipped contracts |
+| **Best practices** | `docs/best-practices/` | Conversation doctrine |
+| **Building apps** | `docs/building-apps/` | Scaffold apps that depend on the package |
+| **Example apps** | `docs/building-apps/example-apps.md` | Links to external sample repos |
+| **App northern stars** | *your app* `README.md` | Goals, triggers — no flow dumps |
+
+See [documentation layers](../best-practices/documentation-layers.md).

package/docs/guides/extending-events.md

@@ -0,0 +1,155 @@
+# Extending Studio events
+
+Vapi Studio is **event-driven**. Every meaningful turn can emit structured events
+on an in-process Node bus. The OSS package does **not** lock you into a single
+sink — you attach your own listeners (the same way you attach Postgres).
+
+Guidify companion tools (e.g. analytics) subscribe the same way: listen in-process,
+optionally publish to a broker + store. Your app can too.
+
+## Mental model
+
+```text
+Node / Supervisor / Forms / Integrations
+        │
+        ▼
+  EventService.emit / persist / persistAnalyticsTag
+        │
+        ├── console + daily file logs
+        ├── onStudioEvent(...)          ← process-wide Node EventEmitter
+        └── Nest eventListeners[]       ← DI / StudioEventListener
+                │
+                ▼ (your code)
+        Redis Streams / queue / HTTP / warehouse / CRM
+```
+
+**Postgres** = durable conversations. **Event bus** = explainability + side effects.
+Neither is Guidify-hosted — both run on your infra.
+
+`EventService.log(...)` is **console/file only** — it does **not** hit `onStudioEvent`.
+Use `persist` / `emit` / `persistAnalyticsTag` for anything listeners must see.
+
+## Two listener styles
+
+### 1. `onStudioEvent` (any process code)
+
+```ts
+// main.ts — register BEFORE app.listen
+import { onStudioEvent, STUDIO_EVENTS } from '@guidify-ai/vapi-studio';
+
+onStudioEvent(async (event) => {
+  if (event.type === 'ROUTE_DECISION') {
+    // why this node ran
+  }
+  if (event.type === STUDIO_EVENTS.OUTBOUND_NOTIFICATION) {
+    // SMS / outbound channel
+  }
+  if (event.type === 'ANALYTICS_TAG') {
+    // funnel milestone — payload.tag
+  }
+});
+```
+
+### 2. Nest `eventListeners`
+
+```ts
+import { Injectable } from '@nestjs/common';
+import {
+  VapiStudioModule,
+  type StudioEvent,
+  type StudioEventListener,
+} from '@guidify-ai/vapi-studio';
+
+@Injectable()
+export class AuditEventListener implements StudioEventListener {
+  async handle(event: StudioEvent): Promise<void> {
+    // DI-friendly: inject repos, queues, …
+  }
+}
+
+VapiStudioModule.forRoot({
+  // …
+  eventListeners: [AuditEventListener],
+});
+```
+
+Both styles are first-class.
+
+## Sample: Redis Streams broker (like analytics)
+
+Framework does **not** open Redis for you. Your app bridges the bus — same
+optional infra pattern as a second Postgres database for an event store.
+
+Compose stub: [`docker-compose.events.stub.yaml`](./docker-compose.events.stub.yaml)
+
+```ts
+// src/events/redis-event-bridge.ts — register from main.ts
+import { onStudioEvent, type StudioEvent } from '@guidify-ai/vapi-studio';
+import Redis from 'ioredis'; // your dependency
+
+const url = process.env.STUDIO_EVENTS_REDIS_URL?.trim();
+const stream = process.env.STUDIO_EVENTS_REDIS_STREAM?.trim() || 'studio:events';
+
+export function registerRedisEventBridge(): void {
+  if (!url) {
+    console.warn('[events] STUDIO_EVENTS_REDIS_URL unset — bus stays in-process only');
+    return;
+  }
+  const redis = new Redis(url);
+  onStudioEvent(async (event: StudioEvent) => {
+    await redis.xadd(
+      stream,
+      '*',
+      'type', event.type,
+      'ts', event.ts,
+      'conversationId', event.conversationId ?? '',
+      'providerCallId', event.providerCallId ?? '',
+      'payload', JSON.stringify(event.payload ?? {}),
+    );
+  });
+}
+```
+
+```ts
+// main.ts
+import { registerRedisEventBridge } from './events/redis-event-bridge';
+
+registerRedisEventBridge();
+// … NestFactory.create / listen
+```
+
+A separate **consumer** process (analytics, warehouse loader, …) reads the stream
+and writes Postgres / ClickHouse / whatever you own. Env presets:
+
+| Variable | Purpose |
+| --- | --- |
+| `STUDIO_EVENTS_REDIS_URL` | Broker URL (app-owned) |
+| `STUDIO_EVENTS_REDIS_STREAM` | Stream name (default `studio:events`) |
+| `EVENT_STORE_DATABASE_URL` | Optional durable store for the consumer |
+
+## Sample: emit your own domain events
+
+```ts
+// inside a Node
+await ctx.events.persist(ctx.conversationId, 'LEAD_QUALIFIED', {
+  companyName: ctx.memory.companyName,
+});
+
+// funnel milestone (payload.tag only — never payload.funnels)
+await ctx.events.persistAnalyticsTag(ctx.conversationId, 'quote_requested');
+```
+
+## What events exist?
+
+Canonical catalog: [Events & logging — Event catalog](../reference/events-and-logging.md#event-catalog).
+
+Typed constants exported as `STUDIO_EVENTS` (integrations, outbound, tasks). Many
+forensic types are string names (`ROUTE_DECISION`, `FORM_SENDOUT`, …) — filter on
+`event.type`.
+
+## Related
+
+- [Events & logging](../reference/events-and-logging.md)
+- [Environment variables](../reference/environment-variables.md) · [`.env.example`](../../.env.example)
+- [Debugging and observability](../best-practices/debugging-and-observability.md)
+- [Data model](../reference/data-model.md)

package/docs/guides/node-conventions.md

@@ -0,0 +1,59 @@
+# Node conventions
+
+Human-readable summary of agent-step conventions. Doctrine: [nodes-and-listens.md](../best-practices/nodes-and-listens.md).
+
+## Intention naming
+
+- **Actions:** `is{VerbPast}…` — `isCollectedFirstName`, `isConfirmedAddressMatch`
+- **Polarity:** `studio.isPositive`, `studio.isNegative`
+- **Framework standard:** `studio.isGoodbye`, `studio.isStillThere`, …
+
+## Node method order
+
+Declare in source in **runtime call order**:
+
+1. `before()` — CAN gate **and** async prep (auth warm, JWT spawn, lookups needed to authorize). Prefer non-blocking spawn when speech must not wait; `await` only for the gate.
+2. `listen()` — register extract / intentions (before speech completes); no I/O
+3. `run()` — speech + one terminal output only; do not overload with integrations that belong in `before()` / `after()`
+4. `after()` — teardown / non-speech side effects after the terminal action (no TTS)
+5. `catch()` — only when overridden
+
+Doctrine: [nodes-and-listens.md](../best-practices/nodes-and-listens.md#prefer-before--after-for-async-work).
+
+## Brain (live ChatGPT path)
+
+- No Custom LLM listen-hold before scan
+- Scan abort ≤ 3s
+- Target first speech < 1.5s after request
+- Model in `VapiStudioModule.forRoot({ brain })` or `brain.config.ts` — not `.env`
+- `interruptible: false` — queue overlapping POSTs until 3s silence, then one scan
+- End of call: `BRAIN_COST_SUMMARY` when usage tracked
+
+## Listed choices
+
+After numbered options, always the same closing question pattern via `listedChoiceQuestion` / `listedChoiceListen` — pick N or neither.
+
+Soft affirmatives that do **not** pick N (“yeah, why not”, bare “sure”) are not a choice — re-ask which option with cheap `resolveIntention`; do not send them to Brain/unknown ([conversation-design.md](../best-practices/conversation-design.md#do-not-auto-pick-lanes)).
+
+## Integrations
+
+```typescript
+await ctx.integrations.request({
+  name: 'my-api',
+  url: 'https://…',
+  body: { … },
+  secretEnvKey: 'MY_HMAC_SECRET',  // env KEY name, not the secret value
+});
+```
+
+JWT HS256 in `x-signature`. Events: `INTEGRATION_REQUEST`, `INTEGRATION_RESPONSE`, `INTEGRATION_ERROR`.
+
+## Shit in, shit out
+
+Do not add Node logic for Vapi stale Custom LLM repeats or “caller repeating previous field.” Unknown / re-ask is enough.
+
+## Related
+
+- [Standard intentions](../reference/standard-intentions.md)
+- [Nodes and listens (doctrine)](../best-practices/nodes-and-listens.md)
+- [Agents](./agents.md)

package/docs/guides/speckit.md

@@ -0,0 +1,56 @@
+# SpecKit
+
+Workspace tooling for specify → plan → tasks → implement workflows under `specs/`.
+
+Config, templates, and scripts live under **`.specify/`** (not under framework-local `.cursor/` — that tree was removed from this package).
+
+## Workflows
+
+| Workflow | Use |
+| --- | --- |
+| specify | Create/update feature spec from description |
+| clarify | Targeted clarification questions → spec |
+| plan | Generate plan from spec template |
+| tasks | Generate `tasks.md` from plan |
+| analyze | Cross-artifact consistency check |
+| checklist | Custom checklist from requirements |
+| implement | Execute tasks from `tasks.md` |
+| converge | Find unbuilt work → append tasks |
+| constitution | Update constitution |
+| taskstoissues | Convert tasks to GitHub issues |
+
+Invoke via SpecKit / Specify CLI against `.specify/` (see `.specify/workflows/`, `.specify/templates/`). IDE skills (`.cursor/skills/speckit-*`, `.claude/skills/speckit-*`) are **not** shipped in this framework package — SpecKit here is `.specify/` only. Reinstall SpecKit skills into a local checkout if you need IDE skill discovery.
+
+## Artifact layout
+
+```text
+specs/<feature-id>/
+├── spec.md
+├── plan.md
+├── tasks.md
+├── research.md
+├── quickstart.md
+├── data-model.md
+└── contracts/
+```
+
+Templates: `.specify/templates/`
+
+## When to use SpecKit vs best practices
+
+| Work | Start here |
+| --- | --- |
+| Day-to-day bot nodes / copy | [Best practices](../best-practices/README.md) + [Agents](./agents.md) |
+| Greenfield framework feature | SpecKit specify → plan → tasks |
+| Compliance check | SpecKit analyze after tasks |
+
+## Historical artifacts
+
+Older SpecKit PoC dumps may exist under a local `archive/` folder (gitignored — not in the repo). Prefer current `docs/` and `docs/reference/runtime-api.md`.
+
+**Authority:** root `README.md` and `docs/` over SpecKit contracts.
+
+## Related
+
+- [Constitution](../reference/principles.md)
+- [Documentation layers](./documentation.md)