@guidify-ai/vapi-studio 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/README.md +13 -4
  2. package/agent/CLAUDE.md +2 -0
  3. package/docs/README.md +3 -0
  4. package/docs/ards/ARD-0001-host-scoped-vapi-ingress.md +45 -0
  5. package/docs/ards/README.md +37 -0
  6. package/docs/building-apps/creating-an-app.md +12 -9
  7. package/docs/building-apps/example-apps.md +1 -1
  8. package/docs/building-apps/overview.md +1 -1
  9. package/docs/getting-started/installation.md +1 -1
  10. package/docs/getting-started/introduction.md +1 -1
  11. package/docs/getting-started/quick-start.md +41 -6
  12. package/docs/guide/module-setup.md +1 -1
  13. package/docs/guides/agents.md +1 -1
  14. package/docs/guides/documentation.md +3 -0
  15. package/docs/guides/speckit.md +30 -14
  16. package/docs/reference/environment-variables.md +4 -0
  17. package/docs/reference/runtime-api.md +1 -1
  18. package/package.json +38 -23
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  **[@guidify-ai/vapi-studio](https://www.npmjs.com/package/@guidify-ai/vapi-studio)** — a **code-driven toolkit for [Vapi](https://vapi.ai)**.
4
4
 
5
- **Website:** [vapi-studio.guidify.ca](https://vapi-studio.guidify.ca)
5
+ **Website:** [vapi-studio.guidify.ca](https://vapi-studio.guidify.ca) — *coming soon*
6
6
 
7
7
  This repo is the **framework** (npm package). Your bot is a separate NestJS app — start from the public starter below.
8
8
 
@@ -10,13 +10,18 @@ This repo is the **framework** (npm package). Your bot is a separate NestJS app
10
10
 
11
11
  ## Create a new project
12
12
 
13
+ `yarn start` alone is not a full setup — fill credentials for **your** path first.
14
+ Full checklist: [Quick start](./docs/getting-started/quick-start.md).
15
+
13
16
  ```bash
14
17
  git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
15
18
  cd my-bot
16
19
  cp .env.example .env
17
- # Edit PROJECT_NAME=… (PROJECT_SLUG optional)
20
+ # Required for live voice: VAPI_API_KEY, POC_ASSISTANT_ID, VAPI_PHONE_NUMBER_ID
21
+ # Optional: TWILIO_* (SMS / Twilio-imported number), OPENAI_API_KEY|ANTHROPIC_… (leave MockBrain otherwise)
22
+ # Always: PROJECT_NAME=… (PROJECT_SLUG optional)
18
23
  yarn install
19
- yarn start # Docker + Postgres + ngrok
24
+ yarn start # Docker + Postgres + ngrok → prints URLs (fails closed without Vapi trio)
20
25
  ```
21
26
 
22
27
  Wire Vapi to the printed URLs:
@@ -30,7 +35,7 @@ Wire Vapi to the printed URLs:
30
35
  - Walkthrough: [Creating an app](./docs/building-apps/creating-an-app.md)
31
36
  - Quick start: [docs/getting-started/quick-start.md](./docs/getting-started/quick-start.md)
32
37
 
33
- **Requirements:** Node 22+, Yarn or npm, Docker Compose, [ngrok](https://ngrok.com/download), a Vapi account.
38
+ **Requirements:** Node 22+, Yarn or npm, Docker Compose, [ngrok](https://ngrok.com/download), a **Vapi** account for live calls. Twilio and an LLM key only when you leave dry-run SMS / MockBrain.
34
39
 
35
40
  **Showcase (not a blank starter):** [vapi-studio-landing-page-sample-model](https://github.com/guidify-ai/vapi-studio-landing-page-sample-model) — Planner LLM demo.
36
41
 
@@ -111,6 +116,8 @@ cd vapi-studio
111
116
  yarn install && yarn build && yarn test
112
117
  ```
113
118
 
119
+ See **[CONTRIBUTING.md](./CONTRIBUTING.md)** — architectural PRs require an **ARD** under `docs/ards/` (SpecKit under `.specify/`).
120
+
114
121
  ---
115
122
 
116
123
  ## Documentation
@@ -122,6 +129,8 @@ yarn install && yarn build && yarn test
122
129
  | Doc site index | [`docs/README.md`](./docs/README.md) |
123
130
  | Runtime handbook | [`docs/reference/runtime-api.md`](./docs/reference/runtime-api.md) |
124
131
  | Best practices | [`docs/best-practices/`](./docs/best-practices/) |
132
+ | ARDs | [`docs/ards/`](./docs/ards/) |
133
+ | SpecKit | [`.specify/`](./.specify/) · [`docs/guides/speckit.md`](./docs/guides/speckit.md) |
125
134
  | Env presets | [`.env.example`](./.env.example) |
126
135
 
127
136
  ## License
package/agent/CLAUDE.md CHANGED
@@ -13,3 +13,5 @@ Canonical agent handbook (shared with Cursor / other agents):
13
13
  - Cursor rule templates (copied into **apps** on postinstall): `agent/cursor/`.
14
14
  - Claude rule templates (copied into **apps** on postinstall): `agent/claude/rules/`.
15
15
  - SpecKit config / templates: `.specify/` (see `docs/guides/speckit.md`).
16
+ - Architecture decisions: `docs/ards/` (required for architectural PRs — `CONTRIBUTING.md`).
17
+ - Constitution (framework only): `.specify/memory/constitution.md`.
package/docs/README.md CHANGED
@@ -47,6 +47,8 @@
47
47
  | --- | --- |
48
48
  | [Documentation layers](./best-practices/documentation-layers.md) | What to update when |
49
49
  | [Agents & Cursor](./guides/agents.md) | AGENTS.md, rules |
50
+ | [SpecKit](./guides/speckit.md) | Framework specify → plan → tasks |
51
+ | [ARDs](./ards/README.md) | Architecture decision records (PR requirement) |
50
52
  | [Node conventions](./guides/node-conventions.md) | Naming, lifecycle, Brain SLOs |
51
53
  | [Extending events](./guides/extending-events.md) | Attach logic to the event bus (Nest + Redis samples) |
52
54
  | [Event samples](./samples/events/) | Copy-paste `onStudioEvent` / Nest listener examples |
@@ -63,6 +65,7 @@
63
65
  | [Runtime API](./reference/runtime-api.md) | Shipped contracts |
64
66
  | [Security](./reference/security.md) | Secrets policy |
65
67
  | [Testing](./reference/testing.md) | `yarn test` |
68
+ | [Contributing](../CONTRIBUTING.md) | PR checklist + ARD rule |
66
69
 
67
70
  ## Handbook
68
71
 
package/docs/ards/ARD-0001-host-scoped-vapi-ingress.md ADDED
@@ -0,0 +1,45 @@
1
+ # ARD-0001: Host-scoped Vapi ingress
2
+
3
+ - **Status:** Accepted
4
+ - **Date:** 2026-09-25
5
+ - **Tags:** framework | adapter | docs
6
+
7
+ ## Context
8
+
9
+ Apps need a stable way to wire Vapi Custom LLM + webhook URLs. A multi-tenant
10
+ path prefix (`/{projectUuid}/vapi/...`) is useful behind a shared reverse proxy,
11
+ but it is not the default contract of a single self-hosted Nest app.
12
+
13
+ ## Decision
14
+
15
+ The framework and public starter document **host-scoped** routes only:
16
+
17
+ | Setting | URL |
18
+ | --- | --- |
19
+ | Webhook | `{PUBLIC_BASE_URL}/vapi/webhook` |
20
+ | Custom LLM | `{PUBLIC_BASE_URL}/vapi/chat/completions` |
21
+
22
+ Internal `projects.id` / UUID rows are for DB FKs and forensics — **not** required
23
+ in Vapi dashboard URLs. Optional UUID prefixes are an operator / proxy concern
24
+ outside the default starter.
25
+
26
+ ## Consequences
27
+
28
+ - **Positive:** One app = one `PUBLIC_BASE_URL`; docs stay simple; matches npm README.
29
+ - **Negative:** Multi-app single-tunnel setups must add their own router (e.g. strip
30
+ or prefix paths) without changing Studio’s app-owned controllers.
31
+ - **Follow-ups:** Keep SMS form URL helpers able to honor `PROJECT_UUID` when set,
32
+ without making UUID paths mandatory in getting-started docs.
33
+
34
+ ## Alternatives considered
35
+
36
+ | Option | Why not |
37
+ | --- | --- |
38
+ | Always require `/{uuid}/vapi/...` | Couples every consumer to Guidify-style multi-app tunneling |
39
+ | Route by Vapi `assistantId` inside Studio | Assistant IDs are forensics, not project selection |
40
+
41
+ ## References
42
+
43
+ - `docs/guide/vapi-adapter.md`
44
+ - `docs/getting-started/quick-start.md`
45
+ - `README.md` (Wire Vapi table)
package/docs/ards/README.md ADDED
@@ -0,0 +1,37 @@
1
+ # Architecture Decision Records (ARDs)
2
+
3
+ Framework-only decisions for `@guidify-ai/vapi-studio`.
4
+
5
+ Consumer bots do **not** put product strategy here — only changes that affect
6
+ the published package contract, runtime, adapters, or docs structure.
7
+
8
+ ## When an ARD is required
9
+
10
+ Open or update an ARD for PRs that:
11
+
12
+ - Change public TypeScript exports / Nest module wiring
13
+ - Alter Supervisor / Brain / listen / portal behavior
14
+ - Change persistence schema or Conversation lifecycle
15
+ - Add or reshape provider adapters (Vapi, forms dispose, …)
16
+ - Change documented contracts in `docs/reference/`
17
+
18
+ **Not required** for typo fixes, test-only cleanups, or doc wording that does
19
+ not change behavior — unless reviewers ask for one.
20
+
21
+ ## Process
22
+
23
+ 1. Copy [`.specify/templates/ard-template.md`](../../.specify/templates/ard-template.md)
24
+ to `docs/ards/ARD-XXXX-<slug>.md` (next free number).
25
+ 2. Fill **Context / Decision / Consequences** before or with the implementation PR.
26
+ 3. Reference the ARD in the PR description.
27
+ 4. Prefer SpecKit (`.specify/`) for larger greenfield work — still end with an ARD
28
+ when the outcome is architectural.
29
+
30
+ ## Index
31
+
32
+ | ARD | Title | Status |
33
+ | --- | --- | --- |
34
+ | [ARD-0001](./ARD-0001-host-scoped-vapi-ingress.md) | Host-scoped Vapi ingress (no project UUID in path) | Accepted |
35
+
36
+ Constitution: [`.specify/memory/constitution.md`](../../.specify/memory/constitution.md)
37
+ Contributing: [CONTRIBUTING.md](../../CONTRIBUTING.md)
package/docs/building-apps/creating-an-app.md CHANGED
@@ -6,30 +6,33 @@ Do not put production secrets or customer flows in the framework repository.
6
6
 
7
7
  ## 1. Clone the starter
8
8
 
9
+ Follow the credential checklist in [Quick start](../getting-started/quick-start.md) — live voice needs Vapi; Twilio and an LLM key are mode-dependent.
10
+
9
11
  ```bash
10
12
  git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
11
13
  cd my-bot
12
14
  cp .env.example .env
13
- # Edit PROJECT_NAME=… (PROJECT_SLUG optional — defaults from the name)
15
+ # PROJECT_NAME=…
16
+ # VAPI_API_KEY + POC_ASSISTANT_ID + VAPI_PHONE_NUMBER_ID # live voice
17
+ # TWILIO_* only if SMS live / Twilio-imported number
18
+ # OPENAI_API_KEY (or Claude/Gemini/Grok) only if leaving MockBrain
14
19
  yarn install
15
20
  yarn start # Docker Postgres + app + ngrok → prints Vapi URLs
16
21
  ```
17
22
 
18
- `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).
23
+ `yarn install` pulls `@guidify-ai/vapi-studio@0.1.1` and stamps Cursor/Claude rules + `AGENTS.md`. Postinstall syncs `config/project.identity.json` from `PROJECT_NAME` / `PROJECT_SLUG`.
19
24
 
20
- ### Live voice prerequisites
25
+ ### Credentials at a glance
21
26
 
22
27
  | Need | Detail |
23
28
  | --- | --- |
24
- | **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. |
25
- | **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`. |
26
- | **Trust Hub / +1** | Twilio Trust Hub + voice geo must allow outbound to **+1**. Trial / blocked geo → `Account not allowed to call +1…`. |
27
- | **Balance** | Recommend ~**$30** with auto-recharge to $30 when balance hits ~$10. |
28
- | **Same account** | `VAPI_PHONE_NUMBER_ID` must be a number imported in Vapi from **that** Twilio account. |
29
+ | **Vapi** (required for live voice) | `VAPI_API_KEY`, `POC_ASSISTANT_ID`, `VAPI_PHONE_NUMBER_ID`. Phone may be **Vapi-managed** or Twilio-imported. Vapi is paid. |
30
+ | **Twilio** (optional) | Live SMS forms and/or BYOK imported numbers: `TWILIO_*`. Keep `TWILIO_SMS_DRY_RUN=1` until ready. |
31
+ | **Brain / LLM** (optional) | Starter uses **MockBrain**. ChatGPT / Claude / Gemini / Grok need the matching API key + adapter switch. |
29
32
 
30
33
  ## 2. Wire Vapi
31
34
 
32
- Paste the printed URLs into your Vapi assistant:
35
+ Paste the printed URLs into your Vapi assistant (or use the starter configure script):
33
36
 
34
37
  | Setting | Endpoint |
35
38
  | --- | --- |
package/docs/building-apps/example-apps.md CHANGED
@@ -20,4 +20,4 @@ Step-by-step: [Creating an app](./creating-an-app.md).
20
20
 
21
21
  ## Showcase (reference implementation)
22
22
 
23
- **[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.
23
+ **[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.1` (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 CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  ```text
8
8
  my-bot/ ← clone of vapi-studio-project
9
- ├── package.json ← "@guidify-ai/vapi-studio": "0.1.0"
9
+ ├── package.json ← "@guidify-ai/vapi-studio": "0.1.1"
10
10
  ├── config/
11
11
  │ ├── project.identity.json ← name + slug (from .env)
12
12
  │ └── flow.yaml
package/docs/getting-started/installation.md CHANGED
@@ -8,7 +8,7 @@ You do **not** install the framework into an empty folder by hand. Clone the sta
8
8
  git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
9
9
  cd my-bot
10
10
  cp .env.example .env
11
- yarn install # installs @guidify-ai/vapi-studio@0.1.0 + stamps agent rules
11
+ yarn install # installs @guidify-ai/vapi-studio@0.1.1 + stamps agent rules
12
12
  yarn start
13
13
  ```
14
14
 
package/docs/getting-started/introduction.md CHANGED
@@ -12,7 +12,7 @@ Your bot is a **separate NestJS app**. Start from **[vapi-studio-project](https:
12
12
 
13
13
  ## What you build
14
14
 
15
- 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.
15
+ A fork of [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project) that depends on `@guidify-ai/vapi-studio@0.1.1`, with Vapi Custom LLM + webhook at `/vapi/...` on your host.
16
16
 
17
17
  ## What this is not
18
18
 
package/docs/getting-started/quick-start.md CHANGED
@@ -1,17 +1,52 @@
1
1
  # Quick start
2
2
 
3
- Clone the public starter, name the project, run it.
3
+ Clone the public starter, fill credentials for **your** setup, run it.
4
+
5
+ ## 1. Machine prerequisites
6
+
7
+ - Node **22+**, Yarn 1.x or npm
8
+ - **Docker** + Compose
9
+ - **[ngrok](https://ngrok.com/download)** (HTTPS tunnel for Vapi)
10
+ - Accounts as needed below
11
+
12
+ ## 2. Credentials (pick your path)
13
+
14
+ You cannot place live calls with an empty `.env`. Fill what your mode needs:
15
+
16
+ | | Always for **live voice** | Optional / mode-dependent |
17
+ | --- | --- | --- |
18
+ | **[Vapi](https://vapi.ai)** (paid) | `VAPI_API_KEY`, `POC_ASSISTANT_ID`, `VAPI_PHONE_NUMBER_ID` | `VAPI_PHONE_NUMBER` (E.164), tool-name overrides |
19
+ | **Phone** | A number **in Vapi** linked to that assistant | **Vapi-managed** number *or* **Twilio-imported** BYOK |
20
+ | **Twilio** | — | Required for **live SMS forms** and recommended if the Vapi number is Twilio-imported (`TWILIO_ACCOUNT_SID` / `TWILIO_AUTH_TOKEN` / `TWILIO_FROM_NUMBER`). Leave `TWILIO_SMS_DRY_RUN=1` until ready. |
21
+ | **Brain / LLM** | — | Starter defaults to **MockBrain** (no key). For ChatGPT / Claude / Gemini / Grok set the matching key and switch the adapter in code — see [`.env.example`](../../.env.example) (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`). |
22
+
23
+ **Minimum to dial:** Vapi key + assistant id + phone number id.
24
+ **Minimum to text HTML forms for real:** Twilio (or keep dry-run).
25
+ **Minimum for local graph / health only:** `PROJECT_NAME` + Docker (mock brain, dry-run SMS).
26
+
27
+ ## 3. Clone and configure
4
28
 
5
29
  ```bash
6
30
  git clone git@github.com:guidify-ai/vapi-studio-project.git my-bot
7
31
  cd my-bot
8
32
  cp .env.example .env
9
- # Edit PROJECT_NAME=… (PROJECT_SLUG optional)
10
- yarn install
11
- yarn start # Docker + Postgres + ngrok → prints Vapi URLs
12
33
  ```
13
34
 
14
- Paste into your Vapi assistant:
35
+ Edit `.env`:
36
+
37
+ 1. `PROJECT_NAME=…` (`PROJECT_SLUG` optional)
38
+ 2. **Vapi** block — required for `yarn start` claim / configure
39
+ 3. **Twilio** — only if you use BYOK voice import and/or live SMS
40
+ 4. **Brain key** — only if you leave MockBrain
41
+
42
+ ```bash
43
+ yarn install # stamps agent rules; writes config/project.identity.json
44
+ yarn start # Docker Postgres + app + ngrok → prints URLs
45
+ ```
46
+
47
+ ## 4. Wire Vapi
48
+
49
+ Paste the printed URLs into the assistant (or let `scripts/configure-vapi.sh` PATCH them):
15
50
 
16
51
  | Setting | URL |
17
52
  | --- | --- |
@@ -20,4 +55,4 @@ Paste into your Vapi assistant:
20
55
 
21
56
  Then extend `src/conversation/` and `config/flow.yaml`. Full walkthrough: [Creating an app](../building-apps/creating-an-app.md).
22
57
 
23
- 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).
58
+ Framework contributors (library, not a bot): clone [vapi-studio](https://github.com/guidify-ai/vapi-studio), `yarn build`, `yarn test` — [Installation](./installation.md).
package/docs/guide/module-setup.md CHANGED
@@ -7,7 +7,7 @@ The [vapi-studio-project](https://github.com/guidify-ai/vapi-studio-project) sta
7
7
  ```json
8
8
  {
9
9
  "dependencies": {
10
- "@guidify-ai/vapi-studio": "0.1.0"
10
+ "@guidify-ai/vapi-studio": "0.1.1"
11
11
  }
12
12
  }
13
13
  ```
package/docs/guides/agents.md CHANGED
@@ -78,7 +78,7 @@ Sources: `agent/cursor/` and `agent/claude/rules/` inside the package. Does not
78
78
 
79
79
  ## SpecKit
80
80
 
81
- Greenfield features: [SpecKit guide](./speckit.md) (`.specify/` in this repo).
81
+ Greenfield features: [SpecKit guide](./speckit.md) (`.specify/` in this repo) + [ARDs](../ards/README.md) for architectural PRs.
82
82
 
83
83
  ## Related
84
84
 
package/docs/guides/documentation.md CHANGED
@@ -3,11 +3,14 @@
3
3
  | Layer | Location | Purpose |
4
4
  | --- | --- | --- |
5
5
  | **Package README** | `README.md` | Install + product framing |
6
+ | **Contributing** | `CONTRIBUTING.md` | PR rules, ARD requirement |
6
7
  | **Doc site** | `docs/README.md` | Navigation |
8
+ | **ARDs** | `docs/ards/` | Architecture decisions (framework only) |
7
9
  | **Runtime handbook** | `docs/reference/runtime-api.md` | Shipped contracts |
8
10
  | **Best practices** | `docs/best-practices/` | Conversation doctrine |
9
11
  | **Building apps** | `docs/building-apps/` | Scaffold apps that depend on the package |
10
12
  | **Example apps** | `docs/building-apps/example-apps.md` | Links to external sample repos |
13
+ | **SpecKit** | `.specify/` + `docs/guides/speckit.md` | Framework feature workflow |
11
14
  | **App northern stars** | *your app* `README.md` | Goals, triggers — no flow dumps |
12
15
 
13
16
  See [documentation layers](../best-practices/documentation-layers.md).
package/docs/guides/speckit.md CHANGED
@@ -1,8 +1,10 @@
1
1
  # SpecKit
2
2
 
3
- Workspace tooling for specify → plan → tasks → implement workflows under `specs/`.
3
+ Workspace tooling for **specify → plan → tasks → implement** on **framework**
4
+ changes. Config lives under **`.specify/`**.
4
5
 
5
- Config, templates, and scripts live under **`.specify/`** (not under framework-local `.cursor/` — that tree was removed from this package).
6
+ Consumer bots: do not dump product strategy into this repo’s SpecKit tree.
7
+ Architectural outcomes MUST land as **ARDs** under [`docs/ards/`](../ards/README.md).
6
8
 
7
9
  ## Workflows
8
10
 
@@ -16,10 +18,12 @@ Config, templates, and scripts live under **`.specify/`** (not under framework-l
16
18
  | checklist | Custom checklist from requirements |
17
19
  | implement | Execute tasks from `tasks.md` |
18
20
  | converge | Find unbuilt work → append tasks |
19
- | constitution | Update constitution |
21
+ | constitution | Update [constitution](../../.specify/memory/constitution.md) |
20
22
  | taskstoissues | Convert tasks to GitHub issues |
21
23
 
22
- 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.
24
+ Invoke via SpecKit / Specify CLI against `.specify/`. IDE skills
25
+ (`.cursor/skills/speckit-*`, …) are **not** shipped in the npm package — reinstall
26
+ locally if you need IDE skill discovery.
23
27
 
24
28
  ## Artifact layout
25
29
 
@@ -34,23 +38,35 @@ specs/<feature-id>/
34
38
  └── contracts/
35
39
  ```
36
40
 
37
- Templates: `.specify/templates/`
41
+ Templates: `.specify/templates/` (includes **`ard-template.md`** for ARDs).
42
+
43
+ ## ARDs (Architecture Decision Records)
44
+
45
+ | Rule | Detail |
46
+ | --- | --- |
47
+ | **Required** | PRs that change framework architecture / public contracts |
48
+ | **Location** | `docs/ards/ARD-XXXX-*.md` |
49
+ | **Template** | `.specify/templates/ard-template.md` |
50
+ | **Index** | [docs/ards/README.md](../ards/README.md) |
51
+
52
+ SpecKit produces working artifacts; the **ARD** is the durable, reviewable
53
+ decision for OSS history. Link SpecKit folders from the ARD when both exist.
38
54
 
39
55
  ## When to use SpecKit vs best practices
40
56
 
41
57
  | Work | Start here |
42
58
  | --- | --- |
43
- | Day-to-day bot nodes / copy | [Best practices](../best-practices/README.md) + [Agents](./agents.md) |
44
- | Greenfield framework feature | SpecKit specify → plan → tasks |
45
- | Compliance check | SpecKit analyze after tasks |
46
-
47
- ## Historical artifacts
59
+ | Day-to-day bot nodes (in an **app** repo) | App best practices + package `docs/best-practices/` |
60
+ | Greenfield **framework** feature | SpecKit specify → plan → tasks → **ARD** |
61
+ | Compliance check | SpecKit analyze + constitution |
48
62
 
49
- 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`.
63
+ ## Authority
50
64
 
51
- **Authority:** root `README.md` and `docs/` over SpecKit contracts.
65
+ 1. [Constitution](../../.specify/memory/constitution.md)
66
+ 2. Shipped [`docs/`](../README.md) + [`docs/reference/runtime-api.md`](../reference/runtime-api.md)
67
+ 3. SpecKit feature folders (ephemeral relative to the above)
52
68
 
53
69
  ## Related
54
70
 
55
- - [Constitution](../reference/principles.md)
56
- - [Documentation layers](./documentation.md)
71
+ - [CONTRIBUTING.md](../../CONTRIBUTING.md)
72
+ - [Documentation map](./documentation.md)
package/docs/reference/environment-variables.md CHANGED
@@ -41,6 +41,10 @@ App identity: **`config/project.identity.json`** (`slug` / `name`). App boot ups
41
41
  | `VAPI_DASHBOARD_CALL_URL` | `https://dashboard.vapi.ai/call/{callId}` | Debug UI link to Vapi call (`{callId}` = `provider_call_id`) |
42
42
  | `CONFIG_DIR` | app `config/` | Flow + `workflow.yaml` root |
43
43
 
44
+ Nest / TypeORM / RxJS peers (and optional Twilio) are **exact versions** on the
45
+ package — see `package.json` / [CONTRIBUTING.md](../../CONTRIBUTING.md). Do not
46
+ float them with `^` in apps that consume Studio.
47
+
44
48
  ### App-owned (documented in `.env.example`, not read by the framework core)
45
49
 
46
50
  | Variable | Purpose |
package/docs/reference/runtime-api.md CHANGED
@@ -23,7 +23,7 @@ Application-specific agent steps, copy, and flows do **not** belong in this repo
23
23
  ```json
24
24
  {
25
25
  "dependencies": {
26
- "@guidify-ai/vapi-studio": "0.1.0"
26
+ "@guidify-ai/vapi-studio": "0.1.1"
27
27
  }
28
28
  }
29
29
  ```
package/package.json CHANGED
@@ -1,8 +1,23 @@
1
1
  {
2
2
  "name": "@guidify-ai/vapi-studio",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Vapi Studio — deterministic voice agents for Vapi (NestJS)",
5
5
  "license": "MIT",
6
+ "keywords": [
7
+ "chat",
8
+ "chat-application",
9
+ "chatbot",
10
+ "chatbots",
11
+ "vapi",
12
+ "vapi-ai",
13
+ "vapi-alternative",
14
+ "vapi-tools",
15
+ "voice-agent",
16
+ "voice-ai",
17
+ "voice-assistant",
18
+ "voice-chat",
19
+ "voip"
20
+ ],
6
21
  "repository": {
7
22
  "type": "git",
8
23
  "url": "git+https://github.com/guidify-ai/vapi-studio.git"
@@ -46,17 +61,17 @@
46
61
  "install-agent-refs": "node scripts/install-agent-refs.cjs"
47
62
  },
48
63
  "dependencies": {
49
- "uuid": "^11.1.0",
50
- "yaml": "^2.7.0"
64
+ "uuid": "11.1.1",
65
+ "yaml": "2.9.0"
51
66
  },
52
67
  "peerDependencies": {
53
- "@nestjs/common": "^11.0.0",
54
- "@nestjs/core": "^11.0.0",
55
- "@nestjs/typeorm": "^11.0.0",
56
- "reflect-metadata": "^0.2.2",
57
- "rxjs": "^7.8.1",
58
- "typeorm": "^0.3.21",
59
- "twilio": "^5.0.0"
68
+ "@nestjs/common": "11.1.29",
69
+ "@nestjs/core": "11.1.29",
70
+ "@nestjs/typeorm": "11.0.3",
71
+ "reflect-metadata": "0.2.2",
72
+ "rxjs": "7.8.2",
73
+ "typeorm": "0.3.31",
74
+ "twilio": "5.4.5"
60
75
  },
61
76
  "peerDependenciesMeta": {
62
77
  "twilio": {
@@ -64,18 +79,18 @@
64
79
  }
65
80
  },
66
81
  "devDependencies": {
67
- "@eslint/js": "^10.0.1",
68
- "@nestjs/common": "^11.0.12",
69
- "@nestjs/core": "^11.0.12",
70
- "@nestjs/typeorm": "^11.0.0",
71
- "@types/node": "^22.13.10",
72
- "@types/uuid": "^10.0.0",
73
- "eslint": "^10.9.1",
74
- "reflect-metadata": "^0.2.2",
75
- "rxjs": "^7.8.2",
76
- "ts-morph": "^28.0.0",
77
- "typeorm": "^0.3.21",
78
- "typescript": "^5.8.2",
79
- "typescript-eslint": "^8.69.0"
82
+ "@eslint/js": "10.0.1",
83
+ "@nestjs/common": "11.1.29",
84
+ "@nestjs/core": "11.1.29",
85
+ "@nestjs/typeorm": "11.0.3",
86
+ "@types/node": "22.13.10",
87
+ "@types/uuid": "10.0.0",
88
+ "eslint": "10.9.1",
89
+ "reflect-metadata": "0.2.2",
90
+ "rxjs": "7.8.2",
91
+ "ts-morph": "28.0.0",
92
+ "typeorm": "0.3.31",
93
+ "typescript": "5.8.2",
94
+ "typescript-eslint": "8.69.0"
80
95
  }
81
96
  }