Skip to content

Commit 73e0816

Browse files
vtkovapivtkovapi
committed
docs: update environment and resource management terminology for organization scope
- Revised `.env.example` to reflect changes from environment-specific to organization-specific configurations. - Updated `AGENTS.md` to clarify resource management under org-scoped directories, including command usage and resource promotion. - Enhanced instructions for setting up new organizations and managing resources accordingly.
1 parent 9359b05 commit 73e0816

2 files changed

Lines changed: 58 additions & 50 deletions

File tree

‎.env.example‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
1-
# Vapi GitOps — copy values into environment-specific files (never commit real keys).
1+
# Vapi GitOps — copy values into org-specific files (never commit real keys).
22
#
3-
# This repo loads secrets from `.env.<environment>` when you run commands, e.g.:
4-
# - `.env.dev` → `npm run push:dev`, `npm run pull:dev`, etc.
5-
# - `.env.stg` → `npm run push:stg`, …
6-
# - `.env.prod` → `npm run push:prod`, …
3+
# This repo loads secrets from `.env.<org>` when you run commands, e.g.:
4+
# - `.env.my-org` → `npm run push -- my-org`, `npm run pull -- my-org`, etc.
5+
# - `.env.my-org-prod` → `npm run push -- my-org-prod`, …
76
#
8-
# You can optionally add `.env.<environment>.local` or `.env.local` for overrides
7+
# You can optionally add `.env.<org>.local` or `.env.local` for overrides
98
# (see `src/config.ts`).
109
#
11-
# Different Vapi organizations (dev vs prod workspaces) need different private API keys.
12-
# Create a separate file per environment and paste the private key for that org only.
10+
# Different Vapi organizations need different private API keys.
11+
# Create a separate file per org slug and paste the private key for that org only.
12+
# Run `npm run setup` for an interactive wizard that creates these files.
1313

1414
# Required: Vapi private API key for the organization you are syncing to.
1515
VAPI_TOKEN=your-vapi-private-key-here

‎AGENTS.md‎

Lines changed: 50 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ This project manages **Vapi voice agent configurations** as code. All resources
66

77
**Prompt quality:** Whenever you create a new assistant or change an existing assistant’s system prompt, read **`docs/Vapi Prompt Optimization Guide.md`** first. It goes deeper on structure, voice constraints, tool usage, and evaluation than the summary in this file.
88

9-
**Environment-scoped resources:** Resources live in `resources/<env>/` (e.g. `resources/dev/`, `resources/prod/`). Each environment directory is isolated — `push:dev` only touches `resources/dev/`, `push:prod` only touches `resources/prod/`. See **`docs/environment-scoped-resources.md`** for the full promotion workflow and rationale.
9+
**Org-scoped resources:** Resources live in `resources/<org>/` (e.g. `resources/my-org/`, `resources/my-org-prod/`). Each org directory is isolated — `npm run push -- my-org` only touches `resources/my-org/`. Run `npm run setup` to create a new org.
1010

11-
**Template-safe first run:** In a fresh clone, prefer `npm run pull:dev:bootstrap` (or the matching env) to refresh `.vapi-state.<env>.json` and credential mappings without materializing the target org's resources into `resources/<env>/`. `push:<env>` will auto-run the same bootstrap sync when it detects empty or stale state for the resources being applied.
11+
**Template-safe first run:** In a fresh clone, prefer `npm run pull -- <org> --bootstrap` to refresh `.vapi-state.<org>.json` and credential mappings without materializing the target org's resources into `resources/<org>/`. `npm run push -- <org>` will auto-run the same bootstrap sync when it detects empty or stale state for the resources being applied.
1212

1313
**Learnings & recipes:** Before configuring resources or debugging issues, read the relevant file in **`docs/learnings/`**. Load only what you need:
1414

@@ -36,20 +36,20 @@ This project manages **Vapi voice agent configurations** as code. All resources
3636

3737
| I want to... | What to do |
3838
| ----------------------------------- | ----------------------------------------------------------------------------- |
39-
| Edit an assistant's system prompt | Edit the markdown body in `resources/<env>/assistants/<name>.md` |
40-
| Change assistant settings | Edit the YAML frontmatter in the same `.md` file |
41-
| Add a new tool | Create `resources/<env>/tools/<name>.yml` |
42-
| Add a new assistant | Create `resources/<env>/assistants/<name>.md` |
43-
| Create a multi-agent squad | Create `resources/<env>/squads/<name>.yml` |
44-
| Add post-call analysis | Create `resources/<env>/structuredOutputs/<name>.yml` |
45-
| Write test simulations | Create files under `resources/<env>/simulations/` |
46-
| Promote resources across envs | Copy files from `resources/dev/` to `resources/stg/` or `resources/prod/` |
47-
| Test webhook event delivery locally | Run `npm run mock:webhook` and tunnel with ngrok |
48-
| Push changes to Vapi | `npm run push:dev` or `npm run push:prod` |
49-
| Pull latest from Vapi | `npm run pull:dev`, `npm run pull:dev:force`, or `npm run pull:dev:bootstrap` |
50-
| Pull one known remote resource | `npm run pull:dev -- assistants --id <uuid>` |
51-
| Push only one file | `npm run push:dev resources/dev/assistants/my-agent.md` |
52-
| Test a call | `npm run call:dev -- -a <assistant-name>` |
39+
| Edit an assistant's system prompt | Edit the markdown body in `resources/<org>/assistants/<name>.md` |
40+
| Change assistant settings | Edit the YAML frontmatter in the same `.md` file |
41+
| Add a new tool | Create `resources/<org>/tools/<name>.yml` |
42+
| Add a new assistant | Create `resources/<org>/assistants/<name>.md` |
43+
| Create a multi-agent squad | Create `resources/<org>/squads/<name>.yml` |
44+
| Add post-call analysis | Create `resources/<org>/structuredOutputs/<name>.yml` |
45+
| Write test simulations | Create files under `resources/<org>/simulations/` |
46+
| Promote resources across orgs | Copy files between `resources/<org-a>/` and `resources/<org-b>/` |
47+
| Test webhook event delivery locally | Run `npm run mock:webhook` and tunnel with ngrok |
48+
| Push changes to Vapi | `npm run push -- <org>` |
49+
| Pull latest from Vapi | `npm run pull -- <org>`, `--force`, or `--bootstrap` |
50+
| Pull one known remote resource | `npm run pull -- <org> --type assistants --id <uuid>` |
51+
| Push only one file | `npm run push -- <org> resources/<org>/assistants/my-agent.md` |
52+
| Test a call | `npm run call -- <org> -a <assistant-name>` |
5353

5454
---
5555

@@ -78,15 +78,14 @@ docs/
7878
└── voicemail-detection.md # Voicemail vs human classification
7979
8080
resources/
81-
├── dev/ # Dev environment resources (push:dev reads here)
81+
├── <org>/ # Org-scoped resources (npm run push -- <org> reads here)
8282
│ ├── assistants/
8383
│ ├── tools/
8484
│ ├── squads/
8585
│ ├── structuredOutputs/
86+
│ ├── evals/
8687
│ └── simulations/
87-
├── stg/ # Staging environment resources (push:stg reads here)
88-
│ └── (same structure)
89-
└── prod/ # Production environment resources (push:prod reads here)
88+
└── <another-org>/ # Another org (each is isolated)
9089
└── (same structure)
9190
9291
scripts/
@@ -101,7 +100,7 @@ scripts/
101100

102101
Assistants are voice agents that handle phone calls. They are defined as **Markdown files with YAML frontmatter**.
103102

104-
**File:** `resources/<env>/assistants/<name>.md`
103+
**File:** `resources/<org>/assistants/<name>.md`
105104

106105
```markdown
107106
---
@@ -313,7 +312,7 @@ artifactPlan:
313312

314313
Tools are functions the assistant can call during a conversation.
315314

316-
**File:** `resources/<env>/tools/<name>.yml`
315+
**File:** `resources/<org>/tools/<name>.yml`
317316

318317
#### Function Tool (calls a webhook)
319318

@@ -412,7 +411,7 @@ function:
412411

413412
Structured outputs extract data from call transcripts after the call ends. They run LLM analysis on the conversation.
414413

415-
**File:** `resources/<env>/structuredOutputs/<name>.yml`
414+
**File:** `resources/<org>/structuredOutputs/<name>.yml`
416415

417416
#### Boolean Output (yes/no evaluation)
418417

@@ -494,12 +493,12 @@ schema:
494493

495494
Squads define multi-agent systems where assistants can hand off to each other.
496495

497-
**File:** `resources/<env>/squads/<name>.yml`
496+
**File:** `resources/<org>/squads/<name>.yml`
498497

499498
```yaml
500499
name: My Squad
501500
members:
502-
- assistantId: intake-agent-a1b2c3d4 # References resources/<env>/assistants/<id>.md
501+
- assistantId: intake-agent-a1b2c3d4 # References resources/<org>/assistants/<id>.md
503502
assistantOverrides: # Override assistant settings within this squad
504503
metadata:
505504
position: # Visual position in dashboard editor
@@ -645,10 +644,10 @@ Resources reference each other by **filename without extension**:
645644

646645
| From | Field | References | Example |
647646
| ------------- | ------------------------------------ | ----------------------- | ----------------------------------------- |
648-
| Assistant | `model.toolIds[]` | Tool files | `- end-call-tool` |
649-
| Assistant | `artifactPlan.structuredOutputIds[]` | Structured Output files | `- customer-data` |
650-
| Squad | `members[].assistantId` | Assistant files | `assistantId: intake-agent-a1b2c3d4` |
651-
| Squad handoff | `destinations[].assistantName` | Assistant `name` field | `assistantName: Booking Assistant` |
647+
| Assistant | `model.toolIds[]` | Tool files | `- end-call-tool` |
648+
| Assistant | `artifactPlan.structuredOutputIds[]` | Structured Output files | `- customer-data` |
649+
| Squad | `members[].assistantId` | Assistant files | `assistantId: intake-agent-a1b2c3d4` |
650+
| Squad handoff | `destinations[].assistantName` | Assistant `name` field | `assistantName: Booking Assistant` |
652651
| Simulation | `personalityId` | Personality files | `personalityId: skeptical-sam-a0000001` |
653652
| Simulation | `scenarioId` | Scenario files | `scenarioId: happy-path-booking-a0000002` |
654653
| Suite | `simulationIds[]` | Simulation test files | `- booking-test-1-a0000001` |
@@ -737,26 +736,35 @@ Concrete example conversations showing expected behavior.
737736
## Available Commands
738737

739738
```bash
739+
# Setup
740+
npm run setup # Interactive wizard: API key, org slug, resource selection
741+
740742
# Sync
741-
npm run pull:dev # Pull from Vapi (preserve local changes)
742-
npm run pull:dev:force # Pull from Vapi (overwrite everything)
743-
npm run pull:dev:bootstrap # Refresh state without writing remote resources locally
744-
npm run pull:dev -- squads --id <uuid> # Pull one known remote resource by UUID
745-
# `--id` requires exactly one resource type; it will error if omitted or combined with multiple types
746-
npm run push:dev # Push all local changes to Vapi
747-
npm run push:dev assistants # Push only assistants
748-
npm run push:dev resources/dev/assistants/my-agent.md # Push single file
743+
npm run pull -- <org> # Pull from Vapi (preserve local changes)
744+
npm run pull -- <org> --force # Pull from Vapi (overwrite everything)
745+
npm run pull -- <org> --bootstrap # Refresh state without writing remote resources locally
746+
npm run pull -- <org> --type squads --id <uuid> # Pull one known remote resource by UUID
747+
npm run push -- <org> # Push all local changes to Vapi
748+
npm run push -- <org> assistants # Push only assistants
749+
npm run push -- <org> resources/<org>/assistants/my-agent.md # Push single file
750+
npm run apply -- <org> # Pull then push (full sync)
749751
750752
# Testing
751-
npm run call:dev -- -a <assistant-name> # Call an assistant via WebSocket
752-
npm run call:dev -- -s <squad-name> # Call a squad via WebSocket
753-
npm run mock:webhook # Run local webhook receiver for server message testing
753+
npm run call -- <org> -a <assistant-name> # Call an assistant via WebSocket
754+
npm run call -- <org> -s <squad-name> # Call a squad via WebSocket
755+
npm run eval -- <org> -s <squad-name> # Run evals against a squad
756+
npm run eval -- <org> -a <assistant-name> # Run evals against an assistant
757+
npm run mock:webhook # Run local webhook receiver for server message testing
758+
759+
# Maintenance
760+
npm run cleanup -- <org> # Dry-run: show orphaned remote resources
761+
npm run cleanup -- <org> --force # Delete orphaned remote resources
754762
755763
# Build
756-
npm run build # Type-check
764+
npm run build # Type-check
757765
```
758766

759-
Replace `dev` with `prod` for production environment.
767+
All commands accept an org slug (e.g. `my-org`). Running without arguments launches interactive mode.
760768

761769
---
762770

0 commit comments

Comments
 (0)