docs: refresh repo usage and add webhook testing scaffolding

Update project docs and agent guidance for multi-environment GitOps usage, add a local mock webhook server workflow, and document changelog discipline for significant resource changes.

Author: dhruva2000

.cursor/rules/changelog-updates.mdc

@@ -0,0 +1,19 @@
+---
+description: Require changelog updates for significant config changes
+alwaysApply: true
+---
+
+# Changelog Update Requirement
+
+When making significant configuration changes, update `docs/changelog.md` in the same change.
+
+Significant changes include:
+- Assistant changes (prompt/body/frontmatter updates)
+- Tool changes (new tools, parameter/behavior changes)
+- Squad changes (members, handoffs, overrides, routing)
+- Structured output or simulation changes that affect behavior
+
+Changelog entries should include:
+- Date section (`YYYY-MM-DD`)
+- Resource type and file path(s)
+- What changed, why it changed, and expected impact

.env.example

@@ -0,0 +1,18 @@
+# Vapi GitOps — copy values into environment-specific files (never commit real keys).
+#
+# This repo loads secrets from `.env.<environment>` when you run commands, e.g.:
+#   - `.env.dev`   → `npm run push:dev`, `npm run pull:dev`, etc.
+#   - `.env.stg`   → `npm run push:stg`, …
+#   - `.env.prod`  → `npm run push:prod`, …
+#
+# You can optionally add `.env.<environment>.local` or `.env.local` for overrides
+# (see `src/config.ts`).
+#
+# Different Vapi organizations (dev vs prod workspaces) need different private API keys.
+# Create a separate file per environment and paste the private key for that org only.
+
+# Required: Vapi private API key for the organization you are syncing to.
+VAPI_TOKEN=your-vapi-private-key-here
+
+# Optional: defaults to https://api.vapi.ai if unset (use for local/API proxies only).
+# VAPI_BASE_URL=https://api.vapi.ai

AGENTS.md

@@ -4,6 +4,8 @@ This project manages **Vapi voice agent configurations** as code. All resources
 
 **You do NOT need to know how Vapi works internally.** This guide tells you everything you need to author and modify resources.
 
+**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.
+
 ---
 
 ## Quick Reference
@@ -17,6 +19,8 @@ This project manages **Vapi voice agent configurations** as code. All resources
 | Create a multi-agent squad          | Create `resources/squads/<name>.yml`                            |
 | Add post-call analysis              | Create `resources/structuredOutputs/<name>.yml`                 |
 | Write test simulations              | Create files under `resources/simulations/`                     |
+| Test webhook event delivery locally | Run `npm run mock:webhook` and tunnel with ngrok                |
+| Track significant config updates    | Update `docs/changelog.md`                                      |
 | Push changes to Vapi                | `npm run push:dev` or `npm run push:prod`                       |
 | Pull latest from Vapi               | `npm run pull:dev` or `npm run pull:dev:force`                  |
 | Push only one file                  | `npm run push:dev resources/assistants/my-agent.md`             |
@@ -27,6 +31,10 @@ This project manages **Vapi voice agent configurations** as code. All resources
 ## Project Structure
 
 ```
+docs/
+├── Vapi Prompt Optimization Guide.md   # In-depth prompt authoring (use when creating or editing assistants)
+└── changelog.md                        # Significant resource/config changes over time
+
 resources/
 ├── assistants/              # Voice agent definitions (.md or .yml)
 ├── tools/                   # Tool/function definitions (.yml)
@@ -37,6 +45,9 @@ resources/
     ├── scenarios/           # Test case scripts (.yml)
     ├── tests/               # Simulation runs (.yml)
     └── suites/              # Grouped simulation batches (.yml)
+
+scripts/
+└── mock-vapi-webhook-server.ts        # Local webhook receiver for server message testing
 ```
 
 ---
@@ -601,6 +612,8 @@ The gitops engine resolves these local filenames to Vapi UUIDs automatically dur
 
 The markdown body of an assistant `.md` file is the system prompt — the core instructions that define how the AI behaves on a call. This is the most important part to get right.
 
+**Before drafting or changing prompts:** work through **`docs/Vapi Prompt Optimization Guide.md`** so structure, guardrails, and voice-specific habits stay consistent across agents.
+
 ### Recommended Structure
 
 ```markdown
@@ -670,6 +683,7 @@ npm run push:dev resources/assistants/my-agent.md  # Push single file
 # Testing
 npm run call:dev -- -a <assistant-name>   # Call an assistant via WebSocket
 npm run call:dev -- -s <squad-name>       # Call a squad via WebSocket
+npm run mock:webhook                       # Run local webhook receiver for server message testing
 
 # Build
 npm run build                 # Type-check
@@ -750,3 +764,13 @@ When transferring to human:
 3. Create simulations (pair personality + scenario)
 4. Create suites (batch simulations together)
 5. Run via Vapi dashboard or API
+
+### Mock Server Testing (Webhook/Message Receipt)
+
+If you need a local mock server to validate webhook payloads or message delivery behavior, you can add scripts under `/scripts` (for example: `scripts/mock-vapi-webhook-server.ts`) and run them locally during testing.
+
+- Default expectation: no provider API key is needed for local receive-only mock testing.
+- If a provider-specific key is required, refer to the Vapi monorepo secrets workflow and use `dotenvx` to decrypt the needed values.
+- Assume decryption only works when the corresponding private keys are already available in your zsh environment.
+- For local webhook validation, prioritize core `serverMessages` event types such as `speech-update`, `status-update`, and `end-of-call-report`.
+- To test callbacks from Vapi into your local machine, expose the mock server with a tunnel like `ngrok` and use that public HTTPS URL in `assistant.server.url`.

CLAUDE.md

@@ -0,0 +1,29 @@
+# Project Rules For Claude
+
+This repository uses two instruction sources for Claude:
+
+1. `AGENTS.md` is the primary, comprehensive guide for this codebase.
+2. `CLAUDE.md` contains Claude-specific reinforcement and policy reminders.
+
+When both files exist, follow both. If guidance overlaps, treat `AGENTS.md` as the canonical project playbook and use this file to reinforce Claude-specific behavior.
+
+## Required Reading Order
+
+1. Read `AGENTS.md` first.
+2. Then read this file (`CLAUDE.md`) for additional policy constraints.
+
+## Changelog Discipline
+
+Always update `docs/changelog.md` when making significant configuration changes.
+
+Significant changes include:
+- Assistant updates (prompt or YAML frontmatter)
+- Tool updates (new tools, changed parameters, changed behavior)
+- Squad updates (members, handoffs, overrides)
+- Other behavior-impacting resource changes (structured outputs, simulations)
+
+Each changelog update should state:
+- Date (`YYYY-MM-DD`)
+- Files/resources changed
+- Why the change was made
+- Expected impact

README.md

@@ -37,6 +37,20 @@ Manage Vapi resources via Git using YAML/Markdown as the source-of-truth.
 
 ---
 
+## How to Use This Repo
+
+1. **Sync from Vapi first** using `pull` so local files reflect platform state.
+2. **Edit declarative resources** in `resources/` (`.md` assistants, `.yml` tools/squads/etc.).
+3. **Push selectively while iterating** (resource type or file path), then run a full push before release.
+4. **Promote by environment** (`dev` -> `stg` -> `prod`) using the same resource files with environment-specific state and credentials.
+
+Use:
+- `pull` when Vapi might have changed
+- `push` for explicit deploys
+- `apply` (`pull -> merge -> push`) when you want one command for sync + deploy
+
+---
+
 ## Quick Start
 
 ### Prerequisites
@@ -53,8 +67,13 @@ npm install
 ### Setup Environment
 
 ```bash
-# Create your .env file with your Vapi token
-echo "VAPI_TOKEN=your-token-here" > .env.dev
+# Copy example values, then set real keys
+cp .env.example .env.dev
+cp .env.example .env.stg
+cp .env.example .env.prod
+
+# Add the correct VAPI_TOKEN for each org/environment
+# Note: this repo uses .env.stg (not .env.staging)
 ```
 
 ### Commands
@@ -63,33 +82,48 @@ echo "VAPI_TOKEN=your-token-here" > .env.dev
 |---------|-------------|
 | `npm run build` | Type-check the codebase |
 | `npm run pull:dev` | Pull platform state, preserve local changes |
+| `npm run pull:stg` | Pull staging state, preserve local changes |
 | `npm run pull:dev:force` | Pull platform state, overwrite everything |
+| `npm run pull:stg:force` | Pull staging state, overwrite everything |
 | `npm run pull:prod` | Pull from prod, preserve local changes |
 | `npm run pull:prod:force` | Pull from prod, overwrite everything |
 | `npm run push:dev` | Push local files to Vapi (dev) |
+| `npm run push:stg` | Push local files to Vapi (staging) |
 | `npm run push:prod` | Push local files to Vapi (prod) |
 | `npm run apply:dev` | Pull → Merge → Push in one shot (dev) |
+| `npm run apply:stg` | Pull → Merge → Push in one shot (staging) |
 | `npm run apply:prod` | Pull → Merge → Push in one shot (prod) |
 | `npm run push:dev assistants` | Push only assistants (dev) |
 | `npm run push:dev tools` | Push only tools (dev) |
 | `npm run call:dev -- -a <name>` | Start a WebSocket call to an assistant (dev) |
 | `npm run call:dev -- -s <name>` | Start a WebSocket call to a squad (dev) |
+| `npm run mock:webhook` | Run local webhook receiver for Vapi server messages |
 
 ### Basic Workflow
 
 ```bash
-# First time: pull all resources from Vapi
+# First time: pull all resources from Vapi for your target env
 npm run pull:dev:force
 
 # Commit the initial state
 git add . && git commit -m "initial pull"
 
-# Make changes to YAML/MD files...
+# Make changes to YAML/MD files under resources/
 
-# Push changes to Vapi
+# Push your changes (full sync)
 npm run push:dev
 ```
 
+Promotion example:
+
+```bash
+# After validating in dev, promote selectively to staging
+npm run push:stg resources/squads/your-squad.yml
+
+# Promote to prod when ready
+npm run push:prod resources/squads/your-squad.yml
+```
+
 #### Pulling Without Losing Local Work
 
 By default, `pull` preserves any files you've locally modified or deleted:
@@ -193,12 +227,37 @@ If a dependency already exists on the platform (UUID in the state file) but its
 
 This means you can work on everything in dev, then selectively push a single squad or assistant to staging or prod — no need for a full `push` that touches every resource.
 
+### Webhook Local Testing
+
+Use the local mock receiver when validating Vapi `serverMessages` delivery.
+
+```bash
+# 1) Run local receiver
+npm run mock:webhook
+
+# 2) Expose localhost (example)
+ngrok http 8787
+```
+
+Then set your assistant `server.url` to the ngrok HTTPS URL and include event types like:
+- `speech-update`
+- `status-update`
+- `end-of-call-report`
+
+The mock server exposes:
+- `POST /webhook` (or `POST /`)
+- `GET /health`
+- `GET /events`
+
 ---
 
 ## Project Structure
 
 ```
 vapi-gitops/
+├── docs/
+│   ├── Vapi Prompt Optimization Guide.md   # Prompt authoring reference
+│   └── changelog.md                        # Significant change log
 ├── src/
 │   ├── pull.ts                 # Pull platform state (with git stash/pop merge)
 │   ├── push.ts                 # Push local state to platform
@@ -222,9 +281,14 @@ vapi-gitops/
 │       ├── scenarios/          # Scenario YAML files
 │       ├── tests/              # Simulation YAML files
 │       └── suites/             # Simulation suite YAML files
+├── scripts/
+│   └── mock-vapi-webhook-server.ts # Local server message receiver
+├── .env.example                # Example env var file
 ├── .env.dev                    # Dev environment secrets (gitignored)
+├── .env.stg                    # Staging environment secrets (gitignored)
 ├── .env.prod                   # Prod environment secrets (gitignored)
 ├── .vapi-state.dev.json        # Dev state file
+├── .vapi-state.stg.json        # Staging state file
 └── .vapi-state.prod.json       # Prod state file
 ```