feat: add bootstrap state sync for template pushes

Refresh state and credential mappings without materializing remote org resources, and have push auto-bootstrap when local state is stale or incomplete. Also fix the existing TypeScript build issues needed to keep the repo verifiable.

Author: dhruva-vapi

AGENTS.md

@@ -8,25 +8,27 @@ This project manages **Vapi voice agent configurations** as code. All resources
 
 **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.
 
+**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.
+
 ---
 
 ## Quick Reference
 
-| I want to...                        | What to do                                                                |
-| ----------------------------------- | ------------------------------------------------------------------------- |
-| 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/<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                          |
-| 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/dev/assistants/my-agent.md`                   |
-| Test a call                         | `npm run call:dev -- -a <assistant-name>`                                 |
+| I want to...                        | What to do                                                                    |
+| ----------------------------------- | ----------------------------------------------------------------------------- |
+| 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/<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                              |
+| Push changes to Vapi                | `npm run push:dev` or `npm run push:prod`                                     |
+| Pull latest from Vapi               | `npm run pull:dev`, `npm run pull:dev:force`, or `npm run pull:dev:bootstrap` |
+| Push only one file                  | `npm run push:dev resources/dev/assistants/my-agent.md`                       |
+| Test a call                         | `npm run call:dev -- -a <assistant-name>`                                     |
 
 ---
 
@@ -701,6 +703,7 @@ Concrete example conversations showing expected behavior.
 # Sync
 npm run pull:dev              # Pull from Vapi (preserve local changes)
 npm run pull:dev:force        # Pull from Vapi (overwrite everything)
+npm run pull:dev:bootstrap    # Refresh state without writing remote resources locally
 npm run push:dev              # Push all local changes to Vapi
 npm run push:dev assistants   # Push only assistants
 npm run push:dev resources/dev/assistants/my-agent.md  # Push single file

README.md

@@ -39,7 +39,7 @@ 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.
+1. **Bootstrap state first** using `pull:*:bootstrap` when you need fresh platform mappings without downloading the org's resources into your working tree.
 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`) by copying files between `resources/dev/`, `resources/stg/`, and `resources/prod/`.
@@ -50,6 +50,8 @@ Use:
 - `push` for explicit deploys
 - `apply` (`pull -> merge -> push`) when you want one command for sync + deploy
 
+For template-based repos, `push` now auto-runs a bootstrap state sync when local state is missing credential mappings or contains stale IDs for the resources you're applying.
+
 ---
 
 ## Quick Start
@@ -79,42 +81,58 @@ cp .env.example .env.prod
 
 ### Commands
 
-| Command                         | Description                                         |
-| ------------------------------- | --------------------------------------------------- |
-| `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 |
+| Command                         | Description                                                                |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `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 pull:dev:bootstrap`    | Refresh dev state/credentials without writing remote resources locally     |
+| `npm run pull:stg:bootstrap`    | Refresh staging state/credentials without writing remote resources locally |
+| `npm run pull:prod:bootstrap`   | Refresh prod state/credentials without writing remote resources locally    |
+| `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 for your target env
-npm run pull:dev:force
-
-# Commit the initial state
-git add . && git commit -m "initial pull"
+# First time in a template clone: refresh only state and credentials
+npm run pull:dev:bootstrap
 
-# Make changes to YAML/MD files under resources/
+# Add or edit only the resources you actually want under resources/dev/
 
 # Push your changes (full sync)
 npm run push:dev
 ```
 
+#### Bootstrap State Sync (Template-Safe First Run)
+
+Use bootstrap pull when you need the latest platform IDs and credential mappings but do not want the repo filled with assistants, tools, and other resources from the target Vapi org:
+
+```bash
+npm run pull:dev:bootstrap
+```
+
+This mode:
+
+- Pulls credentials into `.vapi-state.<env>.json`
+- Refreshes remote resource ID mappings in the state file
+- Leaves `resources/<env>/` untouched so your working tree stays focused on the resources you actually intend to manage
+
+If you skip this step, `push` will automatically run the same bootstrap sync when it detects empty or stale state for the resources being applied.
+
 Promotion example:
 
 ```bash

package.json

@@ -24,6 +24,9 @@
     "pull:stg:force": "tsx src/pull.ts stg --force",
     "pull:prod": "tsx src/pull.ts prod",
     "pull:prod:force": "tsx src/pull.ts prod --force",
+    "pull:dev:bootstrap": "tsx src/pull.ts dev --bootstrap",
+    "pull:stg:bootstrap": "tsx src/pull.ts stg --bootstrap",
+    "pull:prod:bootstrap": "tsx src/pull.ts prod --bootstrap",
     "call:dev": "tsx src/call.ts dev",
     "call:stg": "tsx src/call.ts stg",
     "call:prod": "tsx src/call.ts prod",
@@ -45,4 +48,4 @@
     "mic": "^2.1.2",
     "speaker": "^0.5.5"
   }
-}
+}

src/call.ts

@@ -68,15 +68,29 @@ function parseArgs(): CallConfig {
         console.error("❌ Cannot specify both -a and -s");
         process.exit(1);
       }
+      const nextArg = args[i + 1];
+      if (!nextArg) {
+        console.error("❌ Missing assistant name after -a/--assistant");
+        printUsage();
+        process.exit(1);
+      }
       resourceType = "assistant";
-      target = args[++i];
+      target = nextArg;
+      i++;
     } else if (arg === "-s" || arg === "--squad") {
       if (resourceType) {
         console.error("❌ Cannot specify both -a and -s");
         process.exit(1);
       }
+      const nextArg = args[i + 1];
+      if (!nextArg) {
+        console.error("❌ Missing squad name after -s/--squad");
+        printUsage();
+        process.exit(1);
+      }
       resourceType = "squad";
-      target = args[++i];
+      target = nextArg;
+      i++;
     }
   }
 
@@ -536,17 +550,45 @@ function handleControlMessage(
 // Audio Utilities (Stubs - require native modules)
 // ─────────────────────────────────────────────────────────────────────────────
 
+interface SpeakerInstance {
+  write: (data: Buffer) => void;
+  end: () => void;
+}
+
+type SpeakerConstructor = new (options: {
+  channels: number;
+  bitDepth: number;
+  sampleRate: number;
+}) => SpeakerInstance;
+
+interface MicrophoneAudioStream {
+  on: (
+    event: "data" | "error",
+    listener: ((data: Buffer) => void) | ((error: Error) => void),
+  ) => void;
+}
+
+interface MicrophoneInstance {
+  getAudioStream: () => MicrophoneAudioStream;
+  start: () => void;
+  stop: () => void;
+}
+
+type MicrophoneFactory = (
+  options: Record<string, string>,
+) => MicrophoneInstance;
+
 function createAudioContext(): {
   playAudio: (data: Buffer | ArrayBuffer) => void;
   close: () => void;
 } {
   // Lazy load speaker module
-  let Speaker: typeof import("speaker") | null = null;
-  let speakerInstance: InstanceType<typeof import("speaker")> | null = null;
+  let Speaker: SpeakerConstructor | null = null;
+  let speakerInstance: SpeakerInstance | null = null;
 
   try {
     // Dynamic import for optional dependency
-    Speaker = require("speaker");
+    Speaker = require("speaker") as SpeakerConstructor;
     speakerInstance = new Speaker!({
       channels: 1,
       bitDepth: 16,
@@ -577,11 +619,11 @@ function createAudioContext(): {
 function createMicrophoneStream(onData: (data: Buffer) => void): {
   stop: () => void;
 } {
-  let mic: ReturnType<typeof import("mic")> | null = null;
-  let micInstance: ReturnType<ReturnType<typeof import("mic")>> | null = null;
+  let mic: MicrophoneFactory | null = null;
+  let micInstance: MicrophoneInstance | null = null;
 
   try {
-    mic = require("mic");
+    mic = require("mic") as MicrophoneFactory;
     micInstance = mic!({
       rate: "16000",
       channels: "1",