feat(gitops): add .vapi-ignore for explicit resource opt-out

Pull previously had only two terminal states for a remote resource
missing locally: "new resource, pull it" or "locally deleted, skip
forever (state-tracked intent)". There was no way to say "I don't want
this resource managed by my repo at all" without either letting it
sit broken locally or relying on the deletion-intent state forever.

Add a `.vapi-ignore` file (per-environment, gitignore-style) that lets
users explicitly opt resources out of pull. Ignored resources are
never written to disk and never tracked in state, distinct from
"locally deleted" which keeps a UUID mapping. Skip messages now
distinguish three reasons:

  🚫 = matched .vapi-ignore (not tracked)
  ✏️  = locally modified (preserved)
  🗑️  = locally deleted (intent in state)

Pattern syntax is gitignore-flavored with `*`, `**`, and `?` globs
matching against `<folderPath>/<resourceId>`. See
`resources/<env>/.vapi-ignore.example` for documentation.

Author: dhruva-vapi

AGENTS.md

@@ -10,6 +10,8 @@ This project manages **Vapi voice agent configurations** as code. All resources
 
 **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.
 
+**Excluding resources from sync (`.vapi-ignore`):** To prevent specific resources from being pulled at all (e.g. assistants owned by another team or legacy resources you don't want to manage), create `resources/<env>/.vapi-ignore` with gitignore-style patterns. See `resources/<env>/.vapi-ignore.example` for syntax and examples. Ignored resources are silently skipped on every pull and never tracked in state — distinct from "locally deleted" which keeps an entry in state.
+
 **Learnings & recipes:** Before configuring resources or debugging issues, read the relevant file in **`docs/learnings/`**. Load only what you need:
 
 | Working on | Read |

resources/dev/.vapi-ignore.example

@@ -0,0 +1,45 @@
+# .vapi-ignore — explicit opt-out for resources this repo does NOT manage.
+#
+# Resources matching any pattern below are skipped during `pull:<env>` —
+# never written to disk, never tracked in state. Use this for:
+#   - Resources owned by another team or repo
+#   - Legacy/broken resources you don't want to touch
+#   - Resource types you don't care about (e.g. an entire `simulations/**`)
+#
+# To activate this file, copy it to `.vapi-ignore` (no `.example` suffix).
+#
+# ─────────────────────────────────────────────────────────────────────
+# Pattern syntax
+# ─────────────────────────────────────────────────────────────────────
+# Patterns match against `<folderPath>/<resourceId>` (no extension):
+#   - assistants/...
+#   - tools/...
+#   - squads/...
+#   - structuredOutputs/...
+#   - simulations/personalities/...
+#   - simulations/scenarios/...
+#   - simulations/tests/...
+#   - simulations/suites/...
+#
+# Wildcards:
+#   - `*`  matches any characters within a single path segment
+#   - `**` matches across path segments
+#   - `?`  matches a single character
+#
+# Lines starting with `#` are comments. Blank lines are ignored.
+#
+# ─────────────────────────────────────────────────────────────────────
+# Examples
+# ─────────────────────────────────────────────────────────────────────
+
+# Ignore a specific assistant by exact resource ID
+# assistants/ab-assistant-56b80091
+
+# Ignore all assistants whose name starts with `legacy-`
+# assistants/legacy-*
+
+# Ignore an entire resource type
+# simulations/**
+
+# Ignore tools owned by another team
+# tools/team-x-*

resources/prod/.vapi-ignore.example

@@ -0,0 +1,45 @@
+# .vapi-ignore — explicit opt-out for resources this repo does NOT manage.
+#
+# Resources matching any pattern below are skipped during `pull:<env>` —
+# never written to disk, never tracked in state. Use this for:
+#   - Resources owned by another team or repo
+#   - Legacy/broken resources you don't want to touch
+#   - Resource types you don't care about (e.g. an entire `simulations/**`)
+#
+# To activate this file, copy it to `.vapi-ignore` (no `.example` suffix).
+#
+# ─────────────────────────────────────────────────────────────────────
+# Pattern syntax
+# ─────────────────────────────────────────────────────────────────────
+# Patterns match against `<folderPath>/<resourceId>` (no extension):
+#   - assistants/...
+#   - tools/...
+#   - squads/...
+#   - structuredOutputs/...
+#   - simulations/personalities/...
+#   - simulations/scenarios/...
+#   - simulations/tests/...
+#   - simulations/suites/...
+#
+# Wildcards:
+#   - `*`  matches any characters within a single path segment
+#   - `**` matches across path segments
+#   - `?`  matches a single character
+#
+# Lines starting with `#` are comments. Blank lines are ignored.
+#
+# ─────────────────────────────────────────────────────────────────────
+# Examples
+# ─────────────────────────────────────────────────────────────────────
+
+# Ignore a specific assistant by exact resource ID
+# assistants/ab-assistant-56b80091
+
+# Ignore all assistants whose name starts with `legacy-`
+# assistants/legacy-*
+
+# Ignore an entire resource type
+# simulations/**
+
+# Ignore tools owned by another team
+# tools/team-x-*

resources/stg/.vapi-ignore.example

@@ -0,0 +1,45 @@
+# .vapi-ignore — explicit opt-out for resources this repo does NOT manage.
+#
+# Resources matching any pattern below are skipped during `pull:<env>` —
+# never written to disk, never tracked in state. Use this for:
+#   - Resources owned by another team or repo
+#   - Legacy/broken resources you don't want to touch
+#   - Resource types you don't care about (e.g. an entire `simulations/**`)
+#
+# To activate this file, copy it to `.vapi-ignore` (no `.example` suffix).
+#
+# ─────────────────────────────────────────────────────────────────────
+# Pattern syntax
+# ─────────────────────────────────────────────────────────────────────
+# Patterns match against `<folderPath>/<resourceId>` (no extension):
+#   - assistants/...
+#   - tools/...
+#   - squads/...
+#   - structuredOutputs/...
+#   - simulations/personalities/...
+#   - simulations/scenarios/...
+#   - simulations/tests/...
+#   - simulations/suites/...
+#
+# Wildcards:
+#   - `*`  matches any characters within a single path segment
+#   - `**` matches across path segments
+#   - `?`  matches a single character
+#
+# Lines starting with `#` are comments. Blank lines are ignored.
+#
+# ─────────────────────────────────────────────────────────────────────
+# Examples
+# ─────────────────────────────────────────────────────────────────────
+
+# Ignore a specific assistant by exact resource ID
+# assistants/ab-assistant-56b80091
+
+# Ignore all assistants whose name starts with `legacy-`
+# assistants/legacy-*
+
+# Ignore an entire resource type
+# simulations/**
+
+# Ignore tools owned by another team
+# tools/team-x-*

src/config.ts

@@ -261,3 +261,93 @@ export function removeExcludedKeys(
   }
   return filtered;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Ignore Patterns (.vapi-ignore)
+//
+// Resources matching any pattern in resources/<env>/.vapi-ignore are skipped
+// during pull (never written, never tracked). This is the explicit opt-out
+// mechanism for resources that exist on the dashboard but should not be
+// managed by this repo.
+//
+// Pattern syntax (gitignore-flavored, simplified):
+//   - Matches against `<folderPath>/<resourceId>` (no extension)
+//     e.g. `assistants/ab-assistant-56b80091`
+//   - `*`  matches any run of characters within a single path segment
+//   - `**` matches across path segments (zero or more)
+//   - Lines starting with `#` are comments
+//   - Blank lines are ignored
+//   - Leading `!` is reserved for future negation; treated as a comment today
+// ─────────────────────────────────────────────────────────────────────────────
+
+let cachedIgnorePatterns: string[] | null = null;
+
+function getIgnoreFilePath(): string {
+  return join(BASE_DIR, "resources", VAPI_ENV, ".vapi-ignore");
+}
+
+export function loadIgnorePatterns(): string[] {
+  if (cachedIgnorePatterns !== null) return cachedIgnorePatterns;
+
+  const path = getIgnoreFilePath();
+  if (!existsSync(path)) {
+    cachedIgnorePatterns = [];
+    return cachedIgnorePatterns;
+  }
+
+  const raw = readFileSync(path, "utf-8");
+  cachedIgnorePatterns = raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("!"));
+
+  return cachedIgnorePatterns;
+}
+
+// Convert a gitignore-flavored glob to a RegExp. We keep the implementation
+// intentionally small (no node_modules) since pull.ts is the only consumer.
+function compilePattern(pattern: string): RegExp {
+  // Escape regex metacharacters except the glob ones we handle explicitly.
+  // `*` and `?` are translated below; everything else is literal.
+  let regex = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === "*") {
+      // `**` → match any characters including path separators
+      // `*`  → match any characters within a single segment (no `/`)
+      if (pattern[i + 1] === "*") {
+        regex += ".*";
+        i++; // consume the second `*`
+      } else {
+        regex += "[^/]*";
+      }
+    } else if (c === "?") {
+      regex += "[^/]";
+    } else if ("\\^$.|+(){}[]".includes(c as string)) {
+      regex += `\\${c}`;
+    } else {
+      regex += c;
+    }
+  }
+  return new RegExp(`^${regex}$`);
+}
+
+// Check whether a resource at `<folderPath>/<resourceId>` matches the ignore list.
+// Returns the matched pattern (truthy) or null.
+export function matchesIgnore(
+  folderPath: string,
+  resourceId: string,
+  patterns: string[] = loadIgnorePatterns(),
+): string | null {
+  if (patterns.length === 0) return null;
+  const target = `${folderPath}/${resourceId}`;
+  for (const pattern of patterns) {
+    if (compilePattern(pattern).test(target)) return pattern;
+  }
+  return null;
+}
+
+// Test-only: clear the cache. Production code does not need to call this.
+export function _resetIgnoreCache(): void {
+  cachedIgnorePatterns = null;
+}

src/pull.ts

@@ -12,6 +12,8 @@ import {
   BASE_DIR,
   APPLY_FILTER,
   BOOTSTRAP_SYNC,
+  loadIgnorePatterns,
+  matchesIgnore,
 } from "./config.ts";
 import { loadState, saveState } from "./state.ts";
 import { credentialReverseMap, replaceCredentialRefs } from "./credentials.ts";
@@ -669,9 +671,25 @@ export async function pullResourceType(
 
     removeUuidMappings(newStateSection, resource.id, resourceId);
 
+    const folderPath = FOLDER_MAP[resourceType];
+
+    // Skip resources matched by .vapi-ignore.
+    // These are explicit opt-outs — the resource exists on the dashboard but
+    // this repo does not manage it. Do NOT track in state (so a future
+    // un-ignore pulls cleanly and so state doesn't accumulate stale entries).
+    if (!bootstrap && !force) {
+      const matched = matchesIgnore(folderPath, resourceId);
+      if (matched) {
+        console.log(
+          `   🚫 ${resourceId} (matched .vapi-ignore: ${matched})`,
+        );
+        skipped++;
+        continue;
+      }
+    }
+
     // Skip files that have been locally modified (git detection)
     if (!bootstrap && changedFiles) {
-      const folderPath = FOLDER_MAP[resourceType];
       const mdPath = join(
         "resources",
         VAPI_ENV,
@@ -685,24 +703,27 @@ export async function pullResourceType(
         `${resourceId}.yml`,
       );
       if (changedFiles.has(mdPath) || changedFiles.has(ymlPath)) {
-        console.log(`   ⏭️  ${resourceId} (locally changed, skipping)`);
+        console.log(`   ✏️  ${resourceId} (locally modified, preserving)`);
         newStateSection[resourceId] = resource.id;
         skipped++;
         continue;
       }
     }
 
-    // Skip resources whose local file was deleted (works without git)
-    // A resource that was previously tracked (in state) but has no local file = intentional deletion
+    // Skip resources whose local file was deleted (works without git).
+    // A resource that was previously tracked in state but now has no local
+    // file is treated as an intentional deletion. To stop tracking it
+    // entirely (so it never re-appears on pull), add it to .vapi-ignore.
     if (!bootstrap && !force && !isNew) {
-      const folderPath = FOLDER_MAP[resourceType];
       const dir = join(RESOURCES_DIR, folderPath);
       const fileExists =
         existsSync(join(dir, `${resourceId}.md`)) ||
         existsSync(join(dir, `${resourceId}.yml`)) ||
         existsSync(join(dir, `${resourceId}.yaml`));
       if (!fileExists) {
-        console.log(`   ⏭️  ${resourceId} (locally deleted, skipping)`);
+        console.log(
+          `   🗑️  ${resourceId} (deleted locally, intent in state — add to .vapi-ignore to stop tracking)`,
+        );
         newStateSection[resourceId] = resource.id;
         skipped++;
         continue;
@@ -808,13 +829,22 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
     }
     if (changedFiles.size > 0) {
       console.log(
-        `\n📦 ${changedFiles.size} locally changed file(s) will be preserved`,
+        `\n📦 ${changedFiles.size} locally modified file(s) will be preserved`,
       );
       console.log(
         "   Use --force to overwrite all local files with platform state",
       );
     }
-  } else if (force) {
+  }
+
+  const ignorePatterns = !bootstrap && !force ? loadIgnorePatterns() : [];
+  if (ignorePatterns.length > 0) {
+    console.log(
+      `\n🚫 ${ignorePatterns.length} pattern(s) loaded from .vapi-ignore — matching resources will be skipped`,
+    );
+  }
+
+  if (force) {
     console.log(
       "\n⚡ Force mode: overwriting all local files with platform state",
     );
@@ -926,7 +956,12 @@ export async function runPull(options: PullOptions = {}): Promise<PullResult> {
   }
 
   if (totalSkipped > 0) {
-    console.log(`\n   ℹ️  ${totalSkipped} file(s) preserved (locally changed)`);
+    console.log(
+      `\n   ℹ️  ${totalSkipped} resource(s) skipped — see lines above for reasons:`,
+    );
+    console.log("       🚫 = matched .vapi-ignore (not tracked)");
+    console.log("       ✏️  = locally modified (preserved)");
+    console.log("       🗑️  = locally deleted (intent in state)");
     console.log("   Run with --force to overwrite: npm run pull:dev:force");
   }