feat: scope resource directories by environment (dev/stg/prod)

RESOURCES_DIR now resolves to resources/<env>/ so push/pull only
operate on the active environment's files. Fixes a pull.ts bug
where hardcoded paths broke locally-changed-file detection.

Author: dhruva2000

.cursor/rules/changelog-updates.mdc

@@ -1,11 +1,15 @@
 ---
-description: Require changelog updates for significant config changes
+description: Require changelog updates for significant config changes in customer deployments
 alwaysApply: true
 ---
 
 # Changelog Update Requirement
 
-When making significant configuration changes, update `docs/changelog.md` in the same change.
+This rule applies to **customer deployment clones** of the gitops repo, not the root template repo itself.
+
+**How to tell the difference:** If `docs/changelog.md` still contains the placeholder section header `## YYYY-MM-DD`, this is the unmodified template and you should NOT update the changelog. Once that placeholder has been replaced with real dated entries, this is a customer deployment and the rule below applies.
+
+When making significant configuration changes in a customer deployment, update `docs/changelog.md` in the same change.
 
 Significant changes include:
 - Assistant changes (prompt/body/frontmatter updates)

AGENTS.md

@@ -6,24 +6,26 @@ This project manages **Vapi voice agent configurations** as code. All 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.
 
+**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.
+
 ---
 
 ## Quick Reference
 
 | I want to...                        | What to do                                                      |
 |-------------------------------------|-----------------------------------------------------------------|
-| Edit an assistant's system prompt   | Edit the markdown body in `resources/assistants/<name>.md`      |
+| Edit an assistant's system prompt   | Edit the markdown body in `resources/<env>/assistants/<name>.md` |
 | Change assistant settings           | Edit the YAML frontmatter in the same `.md` file                |
-| Add a new tool                      | Create `resources/tools/<name>.yml`                             |
-| Add a new assistant                 | Create `resources/assistants/<name>.md`                         |
-| 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/`                     |
+| Add a new tool                      | Create `resources/<env>/tools/<name>.yml`                       |
+| Add a new assistant                 | Create `resources/<env>/assistants/<name>.md`                   |
+| Create a multi-agent squad          | Create `resources/<env>/squads/<name>.yml`                      |
+| Add post-call analysis              | Create `resources/<env>/structuredOutputs/<name>.yml`           |
+| Write test simulations              | Create files under `resources/<env>/simulations/`               |
+| Promote resources across envs       | Copy files from `resources/dev/` to `resources/stg/` or `resources/prod/` |
 | 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`             |
+| Push only one file                  | `npm run push:dev resources/dev/assistants/my-agent.md`         |
 | Test a call                         | `npm run call:dev -- -a <assistant-name>`                       |
 
 ---
@@ -32,19 +34,21 @@ This project manages **Vapi voice agent configurations** as code. All resources
 
 ```
 docs/
-├── Vapi Prompt Optimization Guide.md   # In-depth prompt authoring (use when creating or editing assistants)
-└── changelog.md                        # Significant resource/config changes over time
+├── Vapi Prompt Optimization Guide.md          # In-depth prompt authoring
+├── environment-scoped-resources.md            # Environment isolation & promotion workflow
+└── changelog.md                               # Template for tracking per-customer config changes
 
 resources/
-├── assistants/              # Voice agent definitions (.md or .yml)
-├── tools/                   # Tool/function definitions (.yml)
-├── structuredOutputs/       # Post-call analysis schemas (.yml)
-├── squads/                  # Multi-agent squad configs (.yml)
-└── simulations/             # Test infrastructure
-    ├── personalities/       # Simulated caller personas (.yml)
-    ├── scenarios/           # Test case scripts (.yml)
-    ├── tests/               # Simulation runs (.yml)
-    └── suites/              # Grouped simulation batches (.yml)
+├── dev/                     # Dev environment resources (push:dev reads here)
+│   ├── assistants/
+│   ├── tools/
+│   ├── squads/
+│   ├── structuredOutputs/
+│   └── simulations/
+├── stg/                     # Staging environment resources (push:stg reads here)
+│   └── (same structure)
+└── prod/                    # Production environment resources (push:prod reads here)
+    └── (same structure)
 
 scripts/
 └── mock-vapi-webhook-server.ts        # Local webhook receiver for server message testing
@@ -58,7 +62,7 @@ scripts/
 
 Assistants are voice agents that handle phone calls. They are defined as **Markdown files with YAML frontmatter**.
 
-**File:** `resources/assistants/<name>.md`
+**File:** `resources/<env>/assistants/<name>.md`
 
 ```markdown
 ---
@@ -266,7 +270,7 @@ artifactPlan:
 
 Tools are functions the assistant can call during a conversation.
 
-**File:** `resources/tools/<name>.yml`
+**File:** `resources/<env>/tools/<name>.yml`
 
 #### Function Tool (calls a webhook)
 
@@ -365,7 +369,7 @@ function:
 
 Structured outputs extract data from call transcripts after the call ends. They run LLM analysis on the conversation.
 
-**File:** `resources/structuredOutputs/<name>.yml`
+**File:** `resources/<env>/structuredOutputs/<name>.yml`
 
 #### Boolean Output (yes/no evaluation)
 
@@ -446,12 +450,12 @@ schema:
 
 Squads define multi-agent systems where assistants can hand off to each other.
 
-**File:** `resources/squads/<name>.yml`
+**File:** `resources/<env>/squads/<name>.yml`
 
 ```yaml
 name: My Squad
 members:
-  - assistantId: intake-agent-a1b2c3d4         # References resources/assistants/<id>.md
+  - assistantId: intake-agent-a1b2c3d4         # References resources/<env>/assistants/<id>.md
     assistantOverrides:                       # Override assistant settings within this squad
       metadata:
         position:                             # Visual position in dashboard editor
@@ -678,7 +682,7 @@ npm run pull:dev              # Pull from Vapi (preserve local changes)
 npm run pull:dev:force        # Pull from Vapi (overwrite everything)
 npm run push:dev              # Push all local changes to Vapi
 npm run push:dev assistants   # Push only assistants
-npm run push:dev resources/assistants/my-agent.md  # Push single file
+npm run push:dev resources/dev/assistants/my-agent.md  # Push single file
 
 # Testing
 npm run call:dev -- -a <assistant-name>   # Call an assistant via WebSocket

CLAUDE.md

@@ -11,19 +11,3 @@ When both files exist, follow both. If guidance overlaps, treat `AGENTS.md` as t
 
 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

@@ -40,9 +40,9 @@ 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.).
+2. **Edit declarative resources** in `resources/<env>/` (`.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.
+4. **Promote by environment** (`dev` -> `stg` -> `prod`) by copying files between `resources/dev/`, `resources/stg/`, and `resources/prod/`.
 
 Use:
 - `pull` when Vapi might have changed
@@ -117,11 +117,13 @@ npm run push:dev
 Promotion example:
 
 ```bash
-# After validating in dev, promote selectively to staging
-npm run push:stg resources/squads/your-squad.yml
+# After validating in dev, copy to staging and push
+cp resources/dev/squads/your-squad.yml resources/stg/squads/
+npm run push:stg
 
 # Promote to prod when ready
-npm run push:prod resources/squads/your-squad.yml
+cp resources/stg/squads/your-squad.yml resources/prod/squads/
+npm run push:prod
 ```
 
 #### Pulling Without Losing Local Work
@@ -133,7 +135,7 @@ By default, `pull` preserves any files you've locally modified or deleted:
 
 npm run pull:dev
 # ⏭️  my-assistant (locally changed, skipping)
-# ✨  new-tool -> resources/tools/new-tool.yml
+# ✨  new-tool -> resources/dev/tools/new-tool.yml
 # Your edits are preserved, new platform resources are downloaded
 ```
 
@@ -156,7 +158,7 @@ npm run pull:dev
 git diff
 
 # Accept platform changes for a specific file
-git checkout -- resources/tools/some-tool.yml
+git checkout -- resources/dev/tools/some-tool.yml
 ```
 
 ### Selective Push (Partial Sync)
@@ -180,17 +182,17 @@ npm run push:dev simulationSuites
 
 ```bash
 # Push a single file
-npm run push:dev resources/assistants/my-assistant.md
+npm run push:dev resources/dev/assistants/my-assistant.md
 
 # Push multiple files
-npm run push:dev resources/assistants/booking.md resources/tools/my-tool.yml
+npm run push:dev resources/dev/assistants/booking.md resources/dev/tools/my-tool.yml
 ```
 
 #### Combined
 
 ```bash
 # Push specific file within a type
-npm run push:dev assistants resources/assistants/booking.md
+npm run push:dev assistants resources/dev/assistants/booking.md
 ```
 
 **Note:** Partial pushes skip deletion checks. Run full `npm run push:dev` to sync deletions.
@@ -202,7 +204,7 @@ Partial push is ideal for promoting specific squads or assistants to staging/pro
 ```bash
 # Push a single squad to staging — tools, structured outputs, and
 # assistants are created automatically if they don't exist yet
-npm run push:stg resources/squads/everblue-voice-squad-20374c37.yml
+npm run push:stg resources/stg/squads/everblue-voice-squad-20374c37.yml
 
 # Push assistants to prod — missing tools and structured outputs
 # are auto-applied first so references resolve correctly
@@ -257,7 +259,8 @@ The mock server exposes:
 vapi-gitops/
 ├── docs/
 │   ├── Vapi Prompt Optimization Guide.md   # Prompt authoring reference
-│   └── changelog.md                        # Significant change log
+│   ├── environment-scoped-resources.md     # Env isolation & promotion workflow
+│   └── changelog.md                        # Template for per-customer change tracking
 ├── src/
 │   ├── pull.ts                 # Pull platform state (with git stash/pop merge)
 │   ├── push.ts                 # Push local state to platform
@@ -272,15 +275,16 @@ vapi-gitops/
 │   ├── credentials.ts          # Credential resolution (name ↔ UUID)
 │   └── delete.ts               # Deletion & orphan checks
 ├── resources/
-│   ├── assistants/             # Assistant files (.md or .yml)
-│   ├── tools/                  # Tool YAML files
-│   ├── structuredOutputs/      # Structured output YAML files
-│   ├── squads/                 # Squad YAML files
-│   └── simulations/            # Simulation resources
-│       ├── personalities/      # Personality YAML files
-│       ├── scenarios/          # Scenario YAML files
-│       ├── tests/              # Simulation YAML files
-│       └── suites/             # Simulation suite YAML files
+│   ├── dev/                    # Dev environment resources (push:dev reads here)
+│   │   ├── assistants/
+│   │   ├── tools/
+│   │   ├── squads/
+│   │   ├── structuredOutputs/
+│   │   └── simulations/
+│   ├── stg/                    # Staging resources (push:stg reads here)
+│   │   └── (same structure)
+│   └── prod/                   # Production resources (push:prod reads here)
+│       └── (same structure)
 ├── scripts/
 │   └── mock-vapi-webhook-server.ts # Local server message receiver
 ├── .env.example                # Example env var file
@@ -440,7 +444,7 @@ simulationIds:
 
 **Option 1: With System Prompt (recommended)**
 
-Create `resources/assistants/my-assistant.md`:
+Create `resources/dev/assistants/my-assistant.md`:
 
 ```markdown
 ---
@@ -461,7 +465,7 @@ Instructions for the assistant...
 
 **Option 2: Without System Prompt**
 
-Create `resources/assistants/my-assistant.yml`:
+Create `resources/dev/assistants/my-assistant.yml`:
 
 ```yaml
 name: My Assistant
@@ -481,7 +485,7 @@ npm run push:dev
 
 ### How to Add a Tool
 
-Create `resources/tools/my-tool.yml`:
+Create `resources/dev/tools/my-tool.yml`:
 
 ```yaml
 type: function
@@ -507,29 +511,29 @@ Use the **filename without extension** as the resource ID:
 # In an assistant
 model:
   toolIds:
-    - my-tool              # → resources/tools/my-tool.yml
-    - utils/helper-tool    # → resources/tools/utils/helper-tool.yml
+    - my-tool              # → resources/<env>/tools/my-tool.yml
+    - utils/helper-tool    # → resources/<env>/tools/utils/helper-tool.yml
 artifactPlan:
   structuredOutputIds:
-    - call-summary         # → resources/structuredOutputs/call-summary.yml
+    - call-summary         # → resources/<env>/structuredOutputs/call-summary.yml
 ```
 
 ```yaml
 # In a squad
 members:
-  - assistantId: intake-agent    # → resources/assistants/intake-agent.md
+  - assistantId: intake-agent    # → resources/<env>/assistants/intake-agent.md
 ```
 
 ```yaml
 # In a simulation
-personalityId: skeptical-sam     # → resources/simulations/personalities/skeptical-sam.yml
-scenarioId: happy-path           # → resources/simulations/scenarios/happy-path.yml
+personalityId: skeptical-sam     # → resources/<env>/simulations/personalities/skeptical-sam.yml
+scenarioId: happy-path           # → resources/<env>/simulations/scenarios/happy-path.yml
 ```
 
 ### How to Delete a Resource
 
 1. **Remove references** to the resource from other files
-2. **Delete the file**: `rm resources/tools/my-tool.yml`
+2. **Delete the file**: `rm resources/dev/tools/my-tool.yml`
 3. **Push**: `npm run push:dev`
 
 The engine will:
@@ -543,7 +547,7 @@ The engine will:
 Create subdirectories for multi-tenant or feature organization:
 
 ```
-resources/
+resources/<env>/
 ├── assistants/
 │   ├── shared/
 │   │   └── fallback.md

docs/changelog.md

@@ -1,41 +1,29 @@
 # Changelog
 
-Use this file to track meaningful configuration changes to assistants, tools, squads, and related resources.
+Track meaningful configuration changes to assistants, tools, squads, and related resources here.
+
+This is a **template file**. When you clone this repo for a customer project, replace the example section below with real entries to start tracking changes specific to that deployment.
 
 ## How To Use
 
 - Add a new dated section at the top for each meaningful change set.
 - Include what changed, why it changed, and expected impact.
 - Group entries by resource type when possible.
+- Remove the `YYYY-MM-DD` example section once you add your first real entry.
 
 ---
 
 ## YYYY-MM-DD
 
 ### Added
-- [assistants] Added `resources/assistants/example-agent.md` for new intake flow.
+- [assistants] Added `resources/<env>/assistants/example-agent.md` for new intake flow.
 
 ### Changed
-- [tools] Updated `resources/tools/example-tool.yml` parameters to include `reasonCode`.
-- [squads] Updated `resources/squads/example-squad.yml` handoff routing logic.
+- [tools] Updated `resources/<env>/tools/example-tool.yml` parameters to include `reasonCode`.
+- [squads] Updated `resources/<env>/squads/example-squad.yml` handoff routing logic.
 
 ### Fixed
-- [assistants] Corrected prompt guardrails in `resources/assistants/example-agent.md`.
+- [assistants] Corrected prompt guardrails in `resources/<env>/assistants/example-agent.md`.
 
 ### Notes
 - Follow-up action or migration notes (if any).
-
----
-
-## 2026-03-25
-
-### Added
-- [testing] Added `scripts/mock-vapi-webhook-server.ts` to receive and inspect webhook events locally.
-- [tooling] Added `npm run mock:webhook` for quickly running the local webhook receiver.
-
-### Changed
-- [docs] Updated `AGENTS.md` mock-server guidance to include core `serverMessages` event types (`speech-update`, `status-update`, `end-of-call-report`) and `ngrok` tunnel usage for local callback testing.
-
-### Notes
-- The mock server includes `GET /health`, `GET /events`, and `POST /webhook` routes.
-- `tool-calls` requests receive a basic mocked `results` response to keep test flows unblocked.