From 8de0fedffabdbdcb6e36c3c2e1cef25a33568745 Mon Sep 17 00:00:00 2001
From: Scott Lowe <scott.lowe@vapi.ai>
Date: Thu, 1 Oct 2026 15:48:54 -0700
Subject: [PATCH] refactor: move resource parsing and org connection helpers
 into config-free modules

The PR check has to read an org's resource files and resolve org keys
without importing config.ts, which parses argv and exits at import time.
Move the code rather than copy it, so push and the check read files the
same way:

- src/resource-parse.ts: FOLDER_MAP, VALID_EXTENSIONS, frontmatter and
  file parsing, the directory scan and loader, .vapi-ignore reading and
  matching, and a new orgResourcesRead(rootDir, org). The two copies of
  the .md body -> system message injection become one function.
- src/org-connection.ts: envValue, tokensParse(envName), connectionLoad
  and childRun from promote-cmd.ts, parameterised on the root dir, token
  variable and base URL.
- api.ts takes VapiApiError, parseApiMessage, shouldRetry and the
  backoff constants from vapi-client.ts and re-exports VapiApiError.
- promotion.ts imports FOLDER_MAP/VALID_EXTENSIONS and exports SLUG_RE
  and the bindings parse/resolve/apply helpers.

resources.ts, config.ts and promote-cmd.ts delegate, and keep their
exports, logs and error messages unchanged.

Refs TEST-141

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/api.ts                   |  43 +---
 src/config.ts                |  77 +------
 src/org-connection.ts        | 112 ++++++++++
 src/promote-cmd.ts           | 105 ++-------
 src/promotion.ts             |  29 +--
 src/resource-parse.ts        | 402 +++++++++++++++++++++++++++++++++++
 src/resources.ts             | 315 ++-------------------------
 src/vapi-client.ts           |   6 +-
 tests/org-connection.test.ts | 200 +++++++++++++++++
 tests/resource-parse.test.ts | 236 ++++++++++++++++++++
 10 files changed, 1023 insertions(+), 502 deletions(-)
 create mode 100644 src/org-connection.ts
 create mode 100644 src/resource-parse.ts
 create mode 100644 tests/org-connection.test.ts
 create mode 100644 tests/resource-parse.test.ts

diff --git a/src/api.ts b/src/api.ts
index a639eab..5fe790c 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -1,5 +1,12 @@
 import { DRY_RUN, VAPI_BASE_URL, VAPI_TOKEN } from "./config.ts";
 import type { VapiResponse } from "./types.ts";
+import {
+  INITIAL_DELAY_MS,
+  MAX_RETRIES,
+  parseApiMessage,
+  shouldRetry,
+  VapiApiError,
+} from "./vapi-client.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Dry-run accounting
@@ -40,32 +47,11 @@ function formatBodyPreview(body: Record<string, unknown>): string {
 // HTTP Client for Vapi API
 // ─────────────────────────────────────────────────────────────────────────────
 
-export class VapiApiError extends Error {
-  constructor(
-    public readonly method: string,
-    public readonly endpoint: string,
-    public readonly statusCode: number,
-    public readonly apiMessage: string,
-    public readonly rawBody: string,
-  ) {
-    super(`API ${method} ${endpoint} failed (${statusCode}): ${apiMessage}`);
-    this.name = "VapiApiError";
-  }
-}
+// The error class, message parsing and retry policy are shared with the
+// config-free client in vapi-client.ts. VapiApiError is re-exported so
+// existing importers and `instanceof` checks see one class.
+export { VapiApiError };
 
-function parseApiMessage(body: string): string {
-  try {
-    const parsed = JSON.parse(body);
-    if (typeof parsed.message === "string") return parsed.message;
-    if (Array.isArray(parsed.message)) return parsed.message.join("; ");
-  } catch {
-    /* not JSON, use raw body */
-  }
-  return body;
-}
-
-const MAX_RETRIES = 5;
-const INITIAL_DELAY_MS = 2000;
 const REQUEST_DELAY_MS = 700; // Delay between requests to avoid rate limits
 
 let lastRequestTime = 0;
@@ -83,13 +69,6 @@ async function throttle(): Promise<void> {
   lastRequestTime = Date.now();
 }
 
-// 429 = rate limit. 5xx = transient server error (gateway timeout, upstream
-// hiccup, deploy in progress). Both are worth retrying with backoff; surfacing
-// a 502 as a hard failure forces the operator to re-run the entire push.
-function shouldRetry(status: number): boolean {
-  return status === 429 || (status >= 500 && status < 600);
-}
-
 export async function vapiRequest<T = VapiResponse>(
   method: "POST" | "PATCH",
   endpoint: string,
diff --git a/src/config.ts b/src/config.ts
index 96220ca..bcd45c2 100644
--- a/src/config.ts
+++ b/src/config.ts
@@ -3,6 +3,10 @@ import { existsSync, readFileSync } from "fs";
 import { basename, dirname, join, relative, resolve } from "path";
 import { fileURLToPath } from "url";
 import type { Environment, ResourceType } from "./types.ts";
+import {
+  ignorePatternsRead,
+  matchesIgnore as matchesIgnorePatterns,
+} from "./resource-parse.ts";
 import { VALID_RESOURCE_TYPES } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -326,76 +330,20 @@ export function removeExcludedKeys(
 // ─────────────────────────────────────────────────────────────────────────────
 // 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
+// Syntax and matching live in resource-parse.ts (config-free); this binds
+// them to the configured org's resources directory and caches the read.
 // ─────────────────────────────────────────────────────────────────────────────
 
 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("!"),
-    );
-
+  cachedIgnorePatterns = ignorePatternsRead(
+    join(BASE_DIR, "resources", VAPI_ENV),
+  );
   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(
@@ -403,12 +351,7 @@ export function matchesIgnore(
   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;
+  return matchesIgnorePatterns(folderPath, resourceId, patterns);
 }
 
 // Test-only: clear the cache. Production code does not need to call this.
diff --git a/src/org-connection.ts b/src/org-connection.ts
new file mode 100644
index 0000000..4bf523f
--- /dev/null
+++ b/src/org-connection.ts
@@ -0,0 +1,112 @@
+// Config-free org connection helpers: resolve an org's API key and base URL
+// from a token map or `.env.<org>`, and run an engine script against that org
+// in a child process. Shared by promotion and the PR check, which both work
+// with several orgs in one process and so can't use config.ts.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveApiKey } from "./api-key.ts";
+
+export interface OrgConnection {
+  token: string;
+  baseUrl?: string;
+}
+
+export function envValue(content: string, key: string): string | undefined {
+  const line = content
+    .split("\n")
+    .find((candidate) => candidate.trimStart().startsWith(`${key}=`));
+  if (!line) return undefined;
+  const value = line.slice(line.indexOf("=") + 1).trim();
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  )
+    return value.slice(1, -1);
+  return value || undefined;
+}
+
+// Parse a JSON `{ "<org>": "<token>" }` map from an env var. Promotion and the
+// PR check use separate variables so each gets only the keys it needs.
+export function tokensParse(envName: string): Map<string, string> {
+  const configured = process.env[envName];
+  if (!configured) return new Map();
+  let raw: unknown;
+  try {
+    raw = JSON.parse(configured);
+  } catch {
+    throw new Error(`${envName} must be valid JSON`);
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error(`${envName} must map org slugs to tokens`);
+  const tokens = new Map<string, string>();
+  for (const [org, token] of Object.entries(raw)) {
+    if (typeof token !== "string" || token.length === 0)
+      throw new Error(
+        `${envName} entry for ${org} must be a non-empty token string`,
+      );
+    tokens.set(org, token);
+  }
+  return tokens;
+}
+
+export interface ConnectionLoadArgs {
+  rootDir: string;
+  org: string;
+  tokens: Map<string, string>;
+  // Named in the "missing token" error so it points at the right variable.
+  tokensEnvName: string;
+  // A configured base URL wins over `.env.<org>`'s VAPI_BASE_URL.
+  baseUrl?: string;
+}
+
+export function connectionLoad(args: ConnectionLoadArgs): OrgConnection {
+  const { rootDir, org, tokens, tokensEnvName } = args;
+  const envPath = resolve(rootDir, `.env.${org}`);
+  const envContent = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+  const envToken = resolveApiKey({
+    VAPI_PRIVATE_API_KEY: envValue(envContent, "VAPI_PRIVATE_API_KEY"),
+    VAPI_TOKEN: envValue(envContent, "VAPI_TOKEN"),
+  });
+  const token = tokens.get(org) ?? envToken;
+  if (!token)
+    throw new Error(
+      `Missing token for org ${org}; set ${tokensEnvName} or .env.${org}`,
+    );
+  return {
+    token,
+    baseUrl: args.baseUrl ?? envValue(envContent, "VAPI_BASE_URL"),
+  };
+}
+
+export interface ChildRunArgs {
+  rootDir: string;
+  script: string;
+  org: string;
+  connection: OrgConnection;
+  args: string[];
+}
+
+// Run `node --import tsx <script> <org> ...args` with the org's key in the
+// environment, so the child's config.ts binds that org.
+export function childRun(run: ChildRunArgs): void {
+  const { rootDir, script, org, connection, args } = run;
+  const environment: NodeJS.ProcessEnv = {
+    ...process.env,
+    VAPI_PRIVATE_API_KEY: connection.token,
+    VAPI_TOKEN: connection.token,
+  };
+  if (connection.baseUrl) environment.VAPI_BASE_URL = connection.baseUrl;
+  if (!connection.baseUrl) delete environment.VAPI_BASE_URL;
+  const result = spawnSync(
+    process.execPath,
+    ["--import", "tsx", script, org, ...args],
+    { cwd: rootDir, env: environment, stdio: "inherit" },
+  );
+  if (result.error)
+    throw new Error(
+      `Failed to run ${script} for ${org}: ${result.error.message}`,
+    );
+  if (result.status !== 0) throw new Error(`${script} failed for ${org}`);
+}
diff --git a/src/promote-cmd.ts b/src/promote-cmd.ts
index 7888191..9cad13a 100644
--- a/src/promote-cmd.ts
+++ b/src/promote-cmd.ts
@@ -1,8 +1,8 @@
-import { resolveApiKey } from "./api-key.ts";
-import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import type { OrgConnection } from "./org-connection.ts";
+import { childRun, connectionLoad, tokensParse } from "./org-connection.ts";
 import type { PromotionConfig, PromotionPipeline } from "./promotion.ts";
 import {
   promotionConfigParse,
@@ -27,11 +27,6 @@ interface PromotionTransition {
   definition: PromotionPipeline;
 }
 
-interface OrgConnection {
-  token: string;
-  baseUrl?: string;
-}
-
 const ROOT_DIR = resolve(
   process.env.VAPI_GITOPS_ROOT ?? fileURLToPath(new URL("..", import.meta.url)),
 );
@@ -106,87 +101,29 @@ function transitionsBuild(
   return transitions;
 }
 
-function envValue(content: string, key: string): string | undefined {
-  const line = content
-    .split("\n")
-    .find((candidate) => candidate.trimStart().startsWith(`${key}=`));
-  if (!line) return undefined;
-  const value = line.slice(line.indexOf("=") + 1).trim();
-  if (
-    (value.startsWith('"') && value.endsWith('"')) ||
-    (value.startsWith("'") && value.endsWith("'"))
-  )
-    return value.slice(1, -1);
-  return value || undefined;
-}
-
-function tokensParse(): Map<string, string> {
-  const configured = process.env.VAPI_PROMOTION_TOKENS;
-  if (!configured) return new Map();
-  let raw: unknown;
-  try {
-    raw = JSON.parse(configured);
-  } catch {
-    throw new Error("VAPI_PROMOTION_TOKENS must be valid JSON");
-  }
-  if (!raw || typeof raw !== "object" || Array.isArray(raw))
-    throw new Error("VAPI_PROMOTION_TOKENS must map org slugs to tokens");
-  const tokens = new Map<string, string>();
-  for (const [org, token] of Object.entries(raw)) {
-    if (typeof token !== "string" || token.length === 0)
-      throw new Error(
-        `VAPI_PROMOTION_TOKENS entry for ${org} must be a non-empty token string`,
-      );
-    tokens.set(org, token);
-  }
-  return tokens;
-}
+const TOKENS_ENV = "VAPI_PROMOTION_TOKENS";
 
-function connectionLoad(
+function orgConnection(
   config: PromotionConfig,
   org: string,
   tokens: Map<string, string>,
 ): OrgConnection {
-  const envPath = resolve(ROOT_DIR, `.env.${org}`);
-  const envContent = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
-  const envToken = resolveApiKey({
-    VAPI_PRIVATE_API_KEY: envValue(envContent, "VAPI_PRIVATE_API_KEY"),
-    VAPI_TOKEN: envValue(envContent, "VAPI_TOKEN"),
+  return connectionLoad({
+    rootDir: ROOT_DIR,
+    org,
+    tokens,
+    tokensEnvName: TOKENS_ENV,
+    baseUrl: config.orgs[org]?.baseUrl,
   });
-  const token = tokens.get(org) ?? envToken;
-  if (!token)
-    throw new Error(
-      `Missing token for org ${org}; set VAPI_PROMOTION_TOKENS or .env.${org}`,
-    );
-  return {
-    token,
-    baseUrl: config.orgs[org]?.baseUrl ?? envValue(envContent, "VAPI_BASE_URL"),
-  };
 }
 
-function childRun(
+function orgScriptRun(
   script: string,
   org: string,
   connection: OrgConnection,
   args: string[],
 ): void {
-  const environment: NodeJS.ProcessEnv = {
-    ...process.env,
-    VAPI_PRIVATE_API_KEY: connection.token,
-    VAPI_TOKEN: connection.token,
-  };
-  if (connection.baseUrl) environment.VAPI_BASE_URL = connection.baseUrl;
-  if (!connection.baseUrl) delete environment.VAPI_BASE_URL;
-  const result = spawnSync(
-    process.execPath,
-    ["--import", "tsx", script, org, ...args],
-    { cwd: ROOT_DIR, env: environment, stdio: "inherit" },
-  );
-  if (result.error)
-    throw new Error(
-      `Failed to run ${script} for ${org}: ${result.error.message}`,
-    );
-  if (result.status !== 0) throw new Error(`${script} failed for ${org}`);
+  childRun({ rootDir: ROOT_DIR, script, org, connection, args });
 }
 
 function stateLoad(org: string) {
@@ -206,16 +143,16 @@ async function transitionRun(
   allowEmptySourceDeletion: boolean,
 ): Promise<boolean> {
   if (apply) {
-    childRun(
+    orgScriptRun(
       "src/pull.ts",
       transition.source,
-      connectionLoad(config, transition.source, tokens),
+      orgConnection(config, transition.source, tokens),
       ["--bootstrap", "--bindings-only"],
     );
-    childRun(
+    orgScriptRun(
       "src/pull.ts",
       transition.target,
-      connectionLoad(config, transition.target, tokens),
+      orgConnection(config, transition.target, tokens),
       ["--bootstrap", "--bindings-only"],
     );
   }
@@ -240,10 +177,10 @@ async function transitionRun(
   const changedPaths = plan.changes.map(
     (change) => `resources/${transition.target}/${change.path}`,
   );
-  childRun(
+  orgScriptRun(
     "src/apply.ts",
     transition.target,
-    connectionLoad(config, transition.target, tokens),
+    orgConnection(config, transition.target, tokens),
     ["--force", "--allow-new-files", "--resolve=ours", ...changedPaths],
   );
   return plan.changes.some((change) => change.kind === "delete");
@@ -257,8 +194,10 @@ export async function promotionCommandRun(
   if (!existsSync(configPath))
     throw new Error("promotion.yml is required at the repository root");
   const config = promotionConfigParse(readFileSync(configPath, "utf8"));
-  const tokens = parsed.apply ? tokensParse() : new Map<string, string>();
-  delete process.env.VAPI_PROMOTION_TOKENS;
+  const tokens = parsed.apply
+    ? tokensParse(TOKENS_ENV)
+    : new Map<string, string>();
+  delete process.env[TOKENS_ENV];
   // Applying a deletion removes the intermediate org's state entry. Carry the
   // reviewed authorization forward so the same deletion can reach later orgs.
   const deletionAuthorizedSources = new Set<string>();
diff --git a/src/promotion.ts b/src/promotion.ts
index b4dbfb3..7ece0a5 100644
--- a/src/promotion.ts
+++ b/src/promotion.ts
@@ -11,6 +11,7 @@ import { dirname, extname, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { FOLDER_MAP, VALID_EXTENSIONS } from "./resource-parse.ts";
 import type { ResourceType, StateFile } from "./types.ts";
 
 type BindingPolicy = "bind" | "omit";
@@ -71,25 +72,13 @@ interface PromotionResource {
   id: string;
 }
 
-interface PromotionBindingsResolved {
+export interface PromotionBindingsResolved {
   credentialReverse: Map<string, string>;
   sourcePhones: Map<string, string>;
   targetPhones: Map<string, string>;
 }
 
-const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
-const FOLDER_MAP: Record<ResourceType, string> = {
-  tools: "tools",
-  structuredOutputs: "structuredOutputs",
-  assistants: "assistants",
-  squads: "squads",
-  personalities: "simulations/personalities",
-  scenarios: "simulations/scenarios",
-  simulations: "simulations/tests",
-  simulationSuites: "simulations/suites",
-  evals: "evals",
-};
-const VALID_EXTENSIONS: readonly string[] = [".yml", ".yaml", ".ts", ".md"];
+export const SLUG_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const REFERENCE_FIELDS: Record<string, ResourceType> = {
   toolId: "tools",
   toolIds: "tools",
@@ -145,7 +134,7 @@ function bindingMap(
   };
 }
 
-function bindings(value: unknown): PromotionBindings {
+export function promotionBindingsParse(value: unknown): PromotionBindings {
   const raw = value === undefined ? {} : object(value, "bindings");
   return {
     credentials: bindingMap(raw.credentials, "bind", "bindings.credentials"),
@@ -165,7 +154,7 @@ export function promotionConfigParse(content: string): PromotionConfig {
       throw new Error(`org ${slug}.baseUrl must be a string`);
     orgs[slug] = {
       baseUrl: typeof org.baseUrl === "string" ? org.baseUrl : undefined,
-      bindings: bindings(org.bindings),
+      bindings: promotionBindingsParse(org.bindings),
     };
   }
   const pipelinesRaw = object(raw.pipelines, "promotion.yml pipelines");
@@ -351,7 +340,7 @@ function envBindings(content: string, prefix: string): Map<string, string> {
   return result;
 }
 
-async function bindingsResolve(
+export async function promotionBindingsResolve(
   root: string,
   source: string,
   target: string,
@@ -383,7 +372,7 @@ function policyFor(map: PromotionBindingMap, alias: string): BindingPolicy {
   return map.aliases[alias] ?? map.aliases[alias.toUpperCase()] ?? map.default;
 }
 
-function bindingsApply(
+export function promotionBindingsApply(
   value: unknown,
   bindings: PromotionBindings,
   resolved: PromotionBindingsResolved,
@@ -582,7 +571,7 @@ export async function promotionPlanBuild(
       }
     }
   }
-  const resolved = await bindingsResolve(
+  const resolved = await promotionBindingsResolve(
     options.rootDir,
     options.source,
     options.target,
@@ -594,7 +583,7 @@ export async function promotionPlanBuild(
   for (const file of wanted.values()) {
     const parsed = await resourceData(file, options.rootDir, options.source);
     const canonical = referencesCanonicalize(parsed.data, options.sourceState);
-    const transformed = bindingsApply(
+    const transformed = promotionBindingsApply(
       canonical,
       bindings,
       resolved,
diff --git a/src/resource-parse.ts b/src/resource-parse.ts
new file mode 100644
index 0000000..36b7971
--- /dev/null
+++ b/src/resource-parse.ts
@@ -0,0 +1,402 @@
+// Config-free resource file reading.
+//
+// resources.ts and config.ts bind one org at import time (config.ts parses
+// argv and exits). The PR check reads an org's files without that, so the
+// scan/parse/ignore logic lives here, parameterised on the directory, and
+// resources.ts and config.ts delegate to it. Push and the check therefore
+// read files the same way.
+
+import { existsSync, readFileSync } from "fs";
+import { readdir, readFile, stat } from "fs/promises";
+import { extname, join, relative } from "path";
+import { parse as parseYaml } from "yaml";
+import { isBackupCopyFile } from "./slug-utils.ts";
+import type { ResourceFile, ResourceType } from "./types.ts";
+
+// Options bag for the load functions. `ignorePatterns` is the symmetric
+// counterpart to pull's filter: when present, ids matching any pattern are
+// dropped from the returned array (with a skip-log) before any caller sees
+// them. Push wires this from `loadIgnorePatterns()`; pass `[]` (or omit) to
+// preserve the pre-change behavior.
+export interface LoadOptions {
+  ignorePatterns?: string[];
+  // Suppress per-file "📦 Loaded" / "📁 No <type> directory" chatter. Used by
+  // scoped (single-file / --type) pushes: the FULL set is still loaded for
+  // reference resolution, but printing every file makes the blast radius look
+  // larger than it is — the caller prints the scoped selection instead.
+  quiet?: boolean;
+}
+
+// Map resource types to their folder paths (relative to resources/)
+export const FOLDER_MAP: Record<ResourceType, string> = {
+  tools: "tools",
+  structuredOutputs: "structuredOutputs",
+  assistants: "assistants",
+  squads: "squads",
+  personalities: "simulations/personalities",
+  scenarios: "simulations/scenarios",
+  simulations: "simulations/tests",
+  simulationSuites: "simulations/suites",
+  evals: "evals",
+};
+
+// Single source of truth for resource file extensions. Imported by
+// `recanonicalize.ts` so the precondition-5 "both files exist" check
+// stays in lockstep with the loader — without this, a `.ts`-authored
+// resource paired with a UUID-suffixed `.ts` twin would be invisible to
+// the safety check and silently allow the data-loss shape the
+// recanonicalize header explicitly refuses.
+export const VALID_EXTENSIONS: readonly string[] = [
+  ".yml",
+  ".yaml",
+  ".ts",
+  ".md",
+];
+
+/**
+ * Parse a markdown file with YAML frontmatter
+ * Format:
+ * ---
+ * key: value
+ * ---
+ * Markdown content (becomes system prompt)
+ */
+export function parseFrontmatter(content: string): {
+  config: Record<string, unknown>;
+  body: string;
+} {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    throw new Error(
+      "Invalid frontmatter format - expected YAML between --- delimiters",
+    );
+  }
+
+  const yamlContent = match[1] ?? "";
+  const body = match[2] ?? "";
+  const config = parseYaml(yamlContent) as Record<string, unknown>;
+
+  return { config, body: body.trim() };
+}
+
+// Parse a `.md` resource: frontmatter is the config and a non-empty body
+// becomes the system message, replacing any system message in the
+// frontmatter. This is what push sends, so the check must build the same.
+export function markdownResourceParse(
+  content: string,
+): Record<string, unknown> {
+  const { config, body } = parseFrontmatter(content);
+
+  if (body) {
+    const model = (config.model as Record<string, unknown>) || {};
+    const existingMessages = Array.isArray(model.messages)
+      ? model.messages
+      : [];
+    model.messages = [
+      { role: "system", content: body },
+      ...existingMessages.filter((m: { role?: string }) => m.role !== "system"),
+    ];
+    config.model = model;
+  }
+
+  return config;
+}
+
+export function parseResourceDataFromFile(
+  filePath: string,
+): Record<string, unknown> {
+  const ext = extname(filePath);
+
+  if (ext === ".md") {
+    return markdownResourceParse(readFileSync(filePath, "utf-8"));
+  }
+
+  const content = readFileSync(filePath, "utf-8");
+  const data = parseYaml(content) as Record<string, unknown>;
+  if (data === null || data === undefined) {
+    throw new Error(`Empty or invalid YAML in ${filePath}`);
+  }
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new Error(`YAML must be an object in ${filePath}`);
+  }
+  return data;
+}
+
+/**
+ * Recursively scan a directory for resource files (.yml, .yaml, .ts)
+ * Warns about unsupported files found in resource directories
+ */
+export async function scanDirectory(
+  dir: string,
+  baseDir: string,
+): Promise<string[]> {
+  // Sort entries so iteration order is identical across filesystems/CI runners.
+  // readdir() returns entries in OS-dependent order (APFS sorts, ext4 doesn't),
+  // and downstream push order affects which resource is created first when
+  // multiple files declare the same resourceId — non-determinism makes that
+  // bug class hard to reproduce.
+  const entries = (await readdir(dir)).slice().sort();
+  const files: string[] = [];
+
+  for (const entry of entries) {
+    // Skip hidden files and directories (e.g., .DS_Store, .gitkeep)
+    if (entry.startsWith(".")) {
+      continue;
+    }
+
+    // Skip dashboard-backup siblings written by the push conflict prompt
+    // ("create local copy + manual merge"). They're reference material for a
+    // hand-merge, not resources — loading one would re-create it on the
+    // platform as a duplicate.
+    if (isBackupCopyFile(entry)) {
+      continue;
+    }
+
+    const fullPath = join(dir, entry);
+    const stats = await stat(fullPath);
+    const relativePath = relative(baseDir, fullPath);
+
+    if (stats.isDirectory()) {
+      // Recursively scan subdirectories
+      const subFiles = await scanDirectory(fullPath, baseDir);
+      files.push(...subFiles);
+    } else {
+      const ext = extname(entry);
+      if (VALID_EXTENSIONS.includes(ext)) {
+        files.push(fullPath);
+      } else {
+        // Warn about unsupported files
+        console.warn(
+          `  ⚠️  Skipping unsupported file: ${relativePath} (expected ${VALID_EXTENSIONS.join(", ")})`,
+        );
+      }
+    }
+  }
+
+  return files;
+}
+
+// Load every resource of one type from `<resourcesDir>/<folder>/`.
+// `loadResources` is this with the configured org's directory.
+export async function resourceDirLoad<T>(
+  type: ResourceType,
+  resourcesDir: string,
+  options: LoadOptions = {},
+): Promise<ResourceFile<T>[]> {
+  const folderPath = FOLDER_MAP[type];
+  const resourceDir = join(resourcesDir, folderPath);
+  const ignorePatterns = options.ignorePatterns ?? [];
+
+  if (!existsSync(resourceDir)) {
+    if (!options.quiet)
+      console.log(`📁 No ${type} directory found, skipping...`);
+    return [];
+  }
+
+  const filePaths = await scanDirectory(resourceDir, resourceDir);
+  const resources: ResourceFile<T>[] = [];
+  const seenIds = new Map<string, string>(); // resourceId -> filePath
+
+  for (const filePath of filePaths) {
+    const ext = extname(filePath);
+
+    // Compute resourceId as path relative to the resource type directory, without extension
+    // e.g., /resources/<org>/assistants/support/intake.yml → support/intake
+    // e.g., /resources/<org>/assistants/inbound-support.yml → inbound-support
+    const relativePath = relative(resourceDir, filePath);
+    const resourceId = relativePath.slice(0, -ext.length);
+
+    // Symmetric ignore: drop matched ids before duplicate-detection and
+    // parsing so the rest of the pipeline never sees the file. Caller passes
+    // `[]` (or omits) to opt out — preserves the pre-change behavior.
+    if (ignorePatterns.length > 0) {
+      const matched = matchesIgnore(folderPath, resourceId, ignorePatterns);
+      if (matched) {
+        console.log(`  🚫 ${resourceId} (matched .vapi-ignore: ${matched})`);
+        continue;
+      }
+    }
+
+    // Check for duplicate resourceIds (e.g., foo.yml and foo.yaml in same directory)
+    if (seenIds.has(resourceId)) {
+      throw new Error(
+        `Duplicate resource ID "${resourceId}" found:\n` +
+          `  - ${seenIds.get(resourceId)}\n` +
+          `  - ${filePath}\n` +
+          `Each resource must have a unique path-based identifier.`,
+      );
+    }
+    seenIds.set(resourceId, filePath);
+
+    let data: T;
+    if (ext === ".ts") {
+      // Dynamic import for TypeScript files
+      try {
+        const module = await import(filePath);
+        data = module.default as T;
+        if (data === undefined) {
+          throw new Error(`No default export found in ${relativePath}`);
+        }
+      } catch (error) {
+        throw new Error(
+          `Failed to import TypeScript resource "${relativePath}": ${error}`,
+        );
+      }
+    } else if (ext === ".md") {
+      // Parse Markdown files with YAML frontmatter (for assistants with system prompts)
+      try {
+        const content = await readFile(filePath, "utf-8");
+        data = markdownResourceParse(content) as T;
+      } catch (error) {
+        throw new Error(
+          `Failed to parse Markdown resource "${relativePath}": ${error}`,
+        );
+      }
+    } else {
+      // Parse YAML files
+      try {
+        const content = await readFile(filePath, "utf-8");
+        data = parseYaml(content) as T;
+        if (data === null || data === undefined) {
+          throw new Error(`Empty or invalid YAML`);
+        }
+        if (typeof data !== "object" || Array.isArray(data)) {
+          throw new Error(
+            `YAML must be an object, got ${Array.isArray(data) ? "array" : typeof data}`,
+          );
+        }
+      } catch (error) {
+        throw new Error(
+          `Failed to parse YAML resource "${relativePath}": ${error}`,
+        );
+      }
+    }
+
+    resources.push({ resourceId, filePath, data });
+    if (!options.quiet) console.log(`  📦 Loaded ${resourceId}`);
+  }
+
+  return resources;
+}
+
+export interface OrgResource {
+  type: ResourceType;
+  id: string;
+  filePath: string;
+  data: Record<string, unknown>;
+}
+
+export interface OrgResourcesReadOptions {
+  // Defaults to the org's own `.vapi-ignore`, which is what push applies.
+  ignorePatterns?: string[];
+  // Defaults to true: callers that aren't push don't want per-file logs.
+  quiet?: boolean;
+}
+
+// Read every resource under `<rootDir>/resources/<org>/`, keyed `type:id`.
+export async function orgResourcesRead(
+  rootDir: string,
+  org: string,
+  options: OrgResourcesReadOptions = {},
+): Promise<Map<string, OrgResource>> {
+  const resourcesDir = join(rootDir, "resources", org);
+  const loadOptions: LoadOptions = {
+    ignorePatterns: options.ignorePatterns ?? ignorePatternsRead(resourcesDir),
+    quiet: options.quiet ?? true,
+  };
+  const resources = new Map<string, OrgResource>();
+  for (const type of Object.keys(FOLDER_MAP) as ResourceType[]) {
+    const files = await resourceDirLoad<Record<string, unknown>>(
+      type,
+      resourcesDir,
+      loadOptions,
+    );
+    for (const file of files) {
+      resources.set(`${type}:${file.resourceId}`, {
+        type,
+        id: file.resourceId,
+        filePath: file.filePath,
+        data: file.data,
+      });
+    }
+  }
+  return resources;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 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
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Read `<resourcesDir>/.vapi-ignore`; a missing file means no patterns.
+export function ignorePatternsRead(resourcesDir: string): string[] {
+  const path = join(resourcesDir, ".vapi-ignore");
+  if (!existsSync(path)) return [];
+
+  const raw = readFileSync(path, "utf-8");
+  return raw
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(
+      (line) =>
+        line.length > 0 && !line.startsWith("#") && !line.startsWith("!"),
+    );
+}
+
+// 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[],
+): 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;
+}
diff --git a/src/resources.ts b/src/resources.ts
index ceb270f..6ac5213 100644
--- a/src/resources.ts
+++ b/src/resources.ts
@@ -1,130 +1,25 @@
-import { existsSync, readFileSync } from "fs";
-import { readdir, readFile, stat } from "fs/promises";
-import { basename, dirname, extname, join, relative, resolve } from "path";
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { basename, extname, join, relative, resolve } from "path";
 import { parse as parseYaml } from "yaml";
 import { BASE_DIR, matchesIgnore, RESOURCES_DIR } from "./config.ts";
+import {
+  FOLDER_MAP,
+  type LoadOptions,
+  markdownResourceParse,
+  parseResourceDataFromFile,
+  resourceDirLoad,
+  VALID_EXTENSIONS,
+} from "./resource-parse.ts";
 import { isBackupCopyFile } from "./slug-utils.ts";
 import { stateUuid } from "./state.ts";
 import { hashPayload } from "./state-serialize.ts";
 import type { ResourceFile, ResourceType, StateFile } from "./types.ts";
 
-// Options bag for the load functions. `ignorePatterns` is the symmetric
-// counterpart to pull's filter: when present, ids matching any pattern are
-// dropped from the returned array (with a skip-log) before any caller sees
-// them. Push wires this from `loadIgnorePatterns()`; pass `[]` (or omit) to
-// preserve the pre-change behavior.
-export interface LoadOptions {
-  ignorePatterns?: string[];
-  // Suppress per-file "📦 Loaded" / "📁 No <type> directory" chatter. Used by
-  // scoped (single-file / --type) pushes: the FULL set is still loaded for
-  // reference resolution, but printing every file makes the blast radius look
-  // larger than it is — the caller prints the scoped selection instead.
-  quiet?: boolean;
-}
-
-// Map resource types to their folder paths (relative to resources/)
-export const FOLDER_MAP: Record<ResourceType, string> = {
-  tools: "tools",
-  structuredOutputs: "structuredOutputs",
-  assistants: "assistants",
-  squads: "squads",
-  personalities: "simulations/personalities",
-  scenarios: "simulations/scenarios",
-  simulations: "simulations/tests",
-  simulationSuites: "simulations/suites",
-  evals: "evals",
-};
-
-// Reverse map: folder path to resource type
-const FOLDER_TO_TYPE: Record<string, ResourceType> = Object.entries(
-  FOLDER_MAP,
-).reduce(
-  (acc, [type, folder]) => {
-    acc[folder] = type as ResourceType;
-    return acc;
-  },
-  {} as Record<string, ResourceType>,
-);
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Resource Loading
-// ─────────────────────────────────────────────────────────────────────────────
-
-// Single source of truth for resource file extensions. Imported by
-// `recanonicalize.ts` so the precondition-5 "both files exist" check
-// stays in lockstep with the loader — without this, a `.ts`-authored
-// resource paired with a UUID-suffixed `.ts` twin would be invisible to
-// the safety check and silently allow the data-loss shape the
-// recanonicalize header explicitly refuses.
-export const VALID_EXTENSIONS: readonly string[] = [
-  ".yml",
-  ".yaml",
-  ".ts",
-  ".md",
-];
-
-/**
- * Parse a markdown file with YAML frontmatter
- * Format:
- * ---
- * key: value
- * ---
- * Markdown content (becomes system prompt)
- */
-function parseFrontmatter(content: string): {
-  config: Record<string, unknown>;
-  body: string;
-} {
-  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-
-  if (!match) {
-    throw new Error(
-      "Invalid frontmatter format - expected YAML between --- delimiters",
-    );
-  }
-
-  const yamlContent = match[1] ?? "";
-  const body = match[2] ?? "";
-  const config = parseYaml(yamlContent) as Record<string, unknown>;
-
-  return { config, body: body.trim() };
-}
-
-function parseResourceDataFromFile(filePath: string): Record<string, unknown> {
-  const ext = extname(filePath);
-
-  if (ext === ".md") {
-    const content = readFileSync(filePath, "utf-8");
-    const { config, body } = parseFrontmatter(content);
-
-    if (body) {
-      const model = (config.model as Record<string, unknown>) || {};
-      const existingMessages = Array.isArray(model.messages)
-        ? model.messages
-        : [];
-      model.messages = [
-        { role: "system", content: body },
-        ...existingMessages.filter(
-          (m: { role?: string }) => m.role !== "system",
-        ),
-      ];
-      config.model = model;
-    }
-
-    return config;
-  }
-
-  const content = readFileSync(filePath, "utf-8");
-  const data = parseYaml(content) as Record<string, unknown>;
-  if (data === null || data === undefined) {
-    throw new Error(`Empty or invalid YAML in ${filePath}`);
-  }
-  if (typeof data !== "object" || Array.isArray(data)) {
-    throw new Error(`YAML must be an object in ${filePath}`);
-  }
-  return data;
-}
+// The file-reading half lives in resource-parse.ts (config-free). These are
+// re-exported so existing importers keep working.
+export { FOLDER_MAP, VALID_EXTENSIONS };
+export type { LoadOptions };
 
 function findLocalResourceFile(
   type: ResourceType,
@@ -153,171 +48,11 @@ export function hashLocalResource(
   }
 }
 
-/**
- * Recursively scan a directory for resource files (.yml, .yaml, .ts)
- * Warns about unsupported files found in resource directories
- */
-async function scanDirectory(dir: string, baseDir: string): Promise<string[]> {
-  // Sort entries so iteration order is identical across filesystems/CI runners.
-  // readdir() returns entries in OS-dependent order (APFS sorts, ext4 doesn't),
-  // and downstream push order affects which resource is created first when
-  // multiple files declare the same resourceId — non-determinism makes that
-  // bug class hard to reproduce.
-  const entries = (await readdir(dir)).slice().sort();
-  const files: string[] = [];
-
-  for (const entry of entries) {
-    // Skip hidden files and directories (e.g., .DS_Store, .gitkeep)
-    if (entry.startsWith(".")) {
-      continue;
-    }
-
-    // Skip dashboard-backup siblings written by the push conflict prompt
-    // ("create local copy + manual merge"). They're reference material for a
-    // hand-merge, not resources — loading one would re-create it on the
-    // platform as a duplicate.
-    if (isBackupCopyFile(entry)) {
-      continue;
-    }
-
-    const fullPath = join(dir, entry);
-    const stats = await stat(fullPath);
-    const relativePath = relative(baseDir, fullPath);
-
-    if (stats.isDirectory()) {
-      // Recursively scan subdirectories
-      const subFiles = await scanDirectory(fullPath, baseDir);
-      files.push(...subFiles);
-    } else {
-      const ext = extname(entry);
-      if (VALID_EXTENSIONS.includes(ext)) {
-        files.push(fullPath);
-      } else {
-        // Warn about unsupported files
-        console.warn(
-          `  ⚠️  Skipping unsupported file: ${relativePath} (expected ${VALID_EXTENSIONS.join(", ")})`,
-        );
-      }
-    }
-  }
-
-  return files;
-}
-
 export async function loadResources<T>(
   type: ResourceType,
   options: LoadOptions = {},
 ): Promise<ResourceFile<T>[]> {
-  const folderPath = FOLDER_MAP[type];
-  const resourceDir = join(RESOURCES_DIR, folderPath);
-  const ignorePatterns = options.ignorePatterns ?? [];
-
-  if (!existsSync(resourceDir)) {
-    if (!options.quiet) console.log(`📁 No ${type} directory found, skipping...`);
-    return [];
-  }
-
-  const filePaths = await scanDirectory(resourceDir, resourceDir);
-  const resources: ResourceFile<T>[] = [];
-  const seenIds = new Map<string, string>(); // resourceId -> filePath
-
-  for (const filePath of filePaths) {
-    const ext = extname(filePath);
-
-    // Compute resourceId as path relative to the resource type directory, without extension
-    // e.g., /resources/<org>/assistants/support/intake.yml → support/intake
-    // e.g., /resources/<org>/assistants/inbound-support.yml → inbound-support
-    const relativePath = relative(resourceDir, filePath);
-    const resourceId = relativePath.slice(0, -ext.length);
-
-    // Symmetric ignore: drop matched ids before duplicate-detection and
-    // parsing so the rest of the pipeline never sees the file. Caller passes
-    // `[]` (or omits) to opt out — preserves the pre-change behavior.
-    if (ignorePatterns.length > 0) {
-      const matched = matchesIgnore(folderPath, resourceId, ignorePatterns);
-      if (matched) {
-        console.log(`  🚫 ${resourceId} (matched .vapi-ignore: ${matched})`);
-        continue;
-      }
-    }
-
-    // Check for duplicate resourceIds (e.g., foo.yml and foo.yaml in same directory)
-    if (seenIds.has(resourceId)) {
-      throw new Error(
-        `Duplicate resource ID "${resourceId}" found:\n` +
-          `  - ${seenIds.get(resourceId)}\n` +
-          `  - ${filePath}\n` +
-          `Each resource must have a unique path-based identifier.`,
-      );
-    }
-    seenIds.set(resourceId, filePath);
-
-    let data: T;
-    if (ext === ".ts") {
-      // Dynamic import for TypeScript files
-      try {
-        const module = await import(filePath);
-        data = module.default as T;
-        if (data === undefined) {
-          throw new Error(`No default export found in ${relativePath}`);
-        }
-      } catch (error) {
-        throw new Error(
-          `Failed to import TypeScript resource "${relativePath}": ${error}`,
-        );
-      }
-    } else if (ext === ".md") {
-      // Parse Markdown files with YAML frontmatter (for assistants with system prompts)
-      try {
-        const content = await readFile(filePath, "utf-8");
-        const { config, body } = parseFrontmatter(content);
-
-        // Inject markdown body as system message if present
-        if (body) {
-          const model = (config.model as Record<string, unknown>) || {};
-          const existingMessages = Array.isArray(model.messages)
-            ? model.messages
-            : [];
-          model.messages = [
-            { role: "system", content: body },
-            ...existingMessages.filter(
-              (m: { role?: string }) => m.role !== "system",
-            ),
-          ];
-          config.model = model;
-        }
-
-        data = config as T;
-      } catch (error) {
-        throw new Error(
-          `Failed to parse Markdown resource "${relativePath}": ${error}`,
-        );
-      }
-    } else {
-      // Parse YAML files
-      try {
-        const content = await readFile(filePath, "utf-8");
-        data = parseYaml(content) as T;
-        if (data === null || data === undefined) {
-          throw new Error(`Empty or invalid YAML`);
-        }
-        if (typeof data !== "object" || Array.isArray(data)) {
-          throw new Error(
-            `YAML must be an object, got ${Array.isArray(data) ? "array" : typeof data}`,
-          );
-        }
-      } catch (error) {
-        throw new Error(
-          `Failed to parse YAML resource "${relativePath}": ${error}`,
-        );
-      }
-    }
-
-    resources.push({ resourceId, filePath, data });
-    if (!options.quiet) console.log(`  📦 Loaded ${resourceId}`);
-  }
-
-  return resources;
+  return resourceDirLoad<T>(type, RESOURCES_DIR, options);
 }
 
 // Match a CLI-supplied path against a folder name. Shared by push (load
@@ -527,23 +262,7 @@ export async function loadSingleResource(
   } else if (ext === ".md") {
     try {
       const content = await readFile(absolutePath, "utf-8");
-      const { config, body } = parseFrontmatter(content);
-
-      if (body) {
-        const model = (config.model as Record<string, unknown>) || {};
-        const existingMessages = Array.isArray(model.messages)
-          ? model.messages
-          : [];
-        model.messages = [
-          { role: "system", content: body },
-          ...existingMessages.filter(
-            (m: { role?: string }) => m.role !== "system",
-          ),
-        ];
-        config.model = model;
-      }
-
-      data = config;
+      data = markdownResourceParse(content);
     } catch (error) {
       throw new Error(
         `Failed to parse Markdown resource "${filePath}": ${error}`,
diff --git a/src/vapi-client.ts b/src/vapi-client.ts
index 7c32959..508bdff 100644
--- a/src/vapi-client.ts
+++ b/src/vapi-client.ts
@@ -3,7 +3,8 @@
 // api.ts is the engine's client, but it imports config.ts, which parses
 // argv and exits at import time and binds a single org. Code that must run
 // for several orgs, without a token, or from tests (sim.ts, the check
-// runner) uses this client instead.
+// runner) uses this client instead. api.ts imports the error class and retry
+// policy from here, so both clients fail and retry the same way.
 
 export interface VapiConnection {
   token: string;
@@ -48,7 +49,8 @@ export function parseApiMessage(body: string): string {
 }
 
 // 429 = rate limit. 5xx = transient server error (gateway timeout, upstream
-// hiccup, deploy in progress).
+// hiccup, deploy in progress). Both are worth retrying with backoff; surfacing
+// a 502 as a hard failure forces the operator to re-run the entire push.
 export function shouldRetry(status: number): boolean {
   return status === 429 || (status >= 500 && status < 600);
 }
diff --git a/tests/org-connection.test.ts b/tests/org-connection.test.ts
new file mode 100644
index 0000000..5bb4899
--- /dev/null
+++ b/tests/org-connection.test.ts
@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import {
+  childRun,
+  connectionLoad,
+  envValue,
+  tokensParse,
+} from "../src/org-connection.ts";
+
+// childRun starts `node --import tsx` in rootDir, so child fixtures live
+// under the repo (gitignored tmp/) where tsx resolves.
+const REPO_TMP = fileURLToPath(new URL("../tmp/", import.meta.url));
+
+function repoTempDir(): string {
+  mkdirSync(REPO_TMP, { recursive: true });
+  return mkdtempSync(join(REPO_TMP, "org-connection-"));
+}
+
+function withEnv<T>(name: string, value: string | undefined, run: () => T): T {
+  const previous = process.env[name];
+  if (value === undefined) delete process.env[name];
+  else process.env[name] = value;
+  try {
+    return run();
+  } finally {
+    if (previous === undefined) delete process.env[name];
+    else process.env[name] = previous;
+  }
+}
+
+test("envValue reads plain and quoted values and ignores other keys", () => {
+  const content = [
+    "VAPI_TOKEN_OTHER=nope",
+    "  VAPI_PRIVATE_API_KEY='quoted-key'",
+    'VAPI_BASE_URL="https://api.eu.vapi.ai"',
+    "EMPTY=",
+  ].join("\n");
+  assert.deepEqual(
+    [
+      envValue(content, "VAPI_PRIVATE_API_KEY"),
+      envValue(content, "VAPI_BASE_URL"),
+      envValue(content, "EMPTY"),
+      envValue(content, "MISSING"),
+    ],
+    ["quoted-key", "https://api.eu.vapi.ai", undefined, undefined],
+  );
+});
+
+test("tokensParse reads the named variable", () => {
+  const tokens = withEnv("TEST_TOKENS", '{"acme":"t1","acme-ci":"t2"}', () =>
+    tokensParse("TEST_TOKENS"),
+  );
+  assert.deepEqual(
+    [...tokens],
+    [
+      ["acme", "t1"],
+      ["acme-ci", "t2"],
+    ],
+  );
+});
+
+test("tokensParse names the variable in every error", () => {
+  const errors = ["not json", "[]", '{"acme":""}'].map((value) =>
+    withEnv("TEST_TOKENS", value, () => {
+      try {
+        tokensParse("TEST_TOKENS");
+        return "no error";
+      } catch (error) {
+        return (error as Error).message;
+      }
+    }),
+  );
+  assert.deepEqual(errors, [
+    "TEST_TOKENS must be valid JSON",
+    "TEST_TOKENS must map org slugs to tokens",
+    "TEST_TOKENS entry for acme must be a non-empty token string",
+  ]);
+});
+
+test("tokensParse returns an empty map when the variable is unset", () => {
+  assert.equal(
+    withEnv("TEST_TOKENS", undefined, () => tokensParse("TEST_TOKENS")).size,
+    0,
+  );
+});
+
+test("connectionLoad prefers the token map, then .env.<org>", () => {
+  const root = mkdtempSync(join(tmpdir(), "org-connection-"));
+  try {
+    writeFileSync(
+      join(root, ".env.acme"),
+      "VAPI_PRIVATE_API_KEY=env-key\nVAPI_BASE_URL=https://api.eu.vapi.ai\n",
+    );
+    const base = { rootDir: root, org: "acme", tokensEnvName: "TEST_TOKENS" };
+    assert.deepEqual(
+      [
+        connectionLoad({ ...base, tokens: new Map([["acme", "map-key"]]) }),
+        connectionLoad({ ...base, tokens: new Map() }),
+        connectionLoad({
+          ...base,
+          tokens: new Map(),
+          baseUrl: "https://configured.example",
+        }),
+      ],
+      [
+        { token: "map-key", baseUrl: "https://api.eu.vapi.ai" },
+        { token: "env-key", baseUrl: "https://api.eu.vapi.ai" },
+        { token: "env-key", baseUrl: "https://configured.example" },
+      ],
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("connectionLoad names the token variable when no key is found", () => {
+  const root = mkdtempSync(join(tmpdir(), "org-connection-"));
+  try {
+    assert.throws(
+      () =>
+        connectionLoad({
+          rootDir: root,
+          org: "acme",
+          tokens: new Map(),
+          tokensEnvName: "VAPI_CHECK_TOKENS",
+        }),
+      {
+        message:
+          "Missing token for org acme; set VAPI_CHECK_TOKENS or .env.acme",
+      },
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("childRun passes the org and its key to the child, and drops an inherited base URL", () => {
+  const root = repoTempDir();
+  try {
+    const out = join(root, "out.json");
+    writeFileSync(
+      join(root, "child.ts"),
+      `import { writeFileSync } from "node:fs";
+writeFileSync(${JSON.stringify(out)}, JSON.stringify({
+  args: process.argv.slice(2),
+  key: process.env.VAPI_PRIVATE_API_KEY,
+  token: process.env.VAPI_TOKEN,
+  baseUrl: process.env.VAPI_BASE_URL ?? null,
+}));
+`,
+    );
+    withEnv("VAPI_BASE_URL", "https://inherited.example", () =>
+      childRun({
+        rootDir: root,
+        script: "child.ts",
+        org: "acme",
+        connection: { token: "secret" },
+        args: ["--bootstrap"],
+      }),
+    );
+    assert.deepEqual(JSON.parse(readFileSync(out, "utf8")), {
+      args: ["acme", "--bootstrap"],
+      key: "secret",
+      token: "secret",
+      baseUrl: null,
+    });
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("childRun throws when the script fails", () => {
+  const root = repoTempDir();
+  try {
+    writeFileSync(join(root, "fail.ts"), "process.exit(4);\n");
+    assert.throws(
+      () =>
+        childRun({
+          rootDir: root,
+          script: "fail.ts",
+          org: "acme",
+          connection: { token: "secret", baseUrl: "https://api.vapi.ai" },
+          args: [],
+        }),
+      { message: "fail.ts failed for acme" },
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
diff --git a/tests/resource-parse.test.ts b/tests/resource-parse.test.ts
new file mode 100644
index 0000000..05af45d
--- /dev/null
+++ b/tests/resource-parse.test.ts
@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import test from "node:test";
+import {
+  ignorePatternsRead,
+  markdownResourceParse,
+  matchesIgnore,
+  orgResourcesRead,
+  parseResourceDataFromFile,
+  resourceDirLoad,
+} from "../src/resource-parse.ts";
+
+// resource-parse.ts is config-free: importing it must not parse argv or
+// exit, which is why this file can import it directly with no org argument.
+
+function fixture(files: Record<string, string>): string {
+  const root = mkdtempSync(join(tmpdir(), "resource-parse-"));
+  for (const [path, content] of Object.entries(files)) {
+    const full = join(root, path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, content);
+  }
+  return root;
+}
+
+async function silenced<T>(run: () => Promise<T>): Promise<T> {
+  const log = console.log;
+  const warn = console.warn;
+  console.log = () => {};
+  console.warn = () => {};
+  try {
+    return await run();
+  } finally {
+    console.log = log;
+    console.warn = warn;
+  }
+}
+
+test("markdownResourceParse makes the body the only system message", () => {
+  const config = markdownResourceParse(
+    [
+      "---",
+      "name: Intake",
+      "model:",
+      "  provider: openai",
+      "  messages:",
+      "    - role: system",
+      "      content: old prompt",
+      "    - role: assistant",
+      "      content: hi",
+      "---",
+      "",
+      "You are the intake agent.",
+      "",
+    ].join("\n"),
+  );
+  assert.deepEqual(config, {
+    name: "Intake",
+    model: {
+      provider: "openai",
+      messages: [
+        { role: "system", content: "You are the intake agent." },
+        { role: "assistant", content: "hi" },
+      ],
+    },
+  });
+});
+
+test("markdownResourceParse leaves the config alone when the body is empty", () => {
+  assert.deepEqual(markdownResourceParse("---\nname: Empty\n---\n\n"), {
+    name: "Empty",
+  });
+});
+
+test("markdownResourceParse rejects a file with no frontmatter", () => {
+  assert.throws(
+    () => markdownResourceParse("just a prompt"),
+    /Invalid frontmatter format/,
+  );
+});
+
+test("parseResourceDataFromFile parses .md the same way the loader does", async () => {
+  const root = fixture({
+    "assistants/a.md": "---\nname: A\n---\nPrompt A\n",
+  });
+  try {
+    const file = join(root, "assistants/a.md");
+    const [loaded] = await silenced(() => resourceDirLoad("assistants", root));
+    assert.deepEqual(parseResourceDataFromFile(file), loaded!.data);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resourceDirLoad loads every format in sorted order and skips hidden and backup files", async () => {
+  const root = fixture({
+    "tools/b-tool.yml": "type: function\nfunction:\n  name: b\n",
+    "tools/a-tool.ts":
+      "export default { type: 'function', function: { name: 'a' } };\n",
+    "tools/nested/c-tool.yaml": "type: endCall\n",
+    "tools/.hidden.yml": "type: endCall\n",
+    "tools/b-tool.bkp.yml": "type: endCall\n",
+    "tools/notes.txt": "not a resource\n",
+  });
+  try {
+    const loaded = await silenced(() => resourceDirLoad("tools", root));
+    assert.deepEqual(
+      loaded.map((file) => [file.resourceId, file.data]),
+      [
+        ["a-tool", { type: "function", function: { name: "a" } }],
+        ["b-tool", { type: "function", function: { name: "b" } }],
+        ["nested/c-tool", { type: "endCall" }],
+      ],
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resourceDirLoad refuses two files with the same resource ID", async () => {
+  const root = fixture({
+    "tools/dup.yml": "type: endCall\n",
+    "tools/dup.yaml": "type: endCall\n",
+  });
+  try {
+    await assert.rejects(
+      silenced(() => resourceDirLoad("tools", root)),
+      /Duplicate resource ID "dup" found/,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resourceDirLoad rejects YAML that isn't an object", async () => {
+  const root = fixture({ "tools/list.yml": "- a\n- b\n" });
+  try {
+    await assert.rejects(
+      silenced(() => resourceDirLoad("tools", root)),
+      /Failed to parse YAML resource "list.yml": Error: YAML must be an object, got array/,
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("resourceDirLoad returns nothing for a missing directory", async () => {
+  const root = fixture({});
+  try {
+    assert.deepEqual(await silenced(() => resourceDirLoad("squads", root)), []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ignorePatternsRead drops comments, blanks and reserved negations", () => {
+  const root = fixture({
+    ".vapi-ignore":
+      "# comment\n\nassistants/legacy-*\n!assistants/keep\n  tools/** \n",
+  });
+  try {
+    assert.deepEqual(ignorePatternsRead(root), [
+      "assistants/legacy-*",
+      "tools/**",
+    ]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("ignorePatternsRead treats a missing file as no patterns", () => {
+  const root = fixture({});
+  try {
+    assert.deepEqual(ignorePatternsRead(root), []);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("matchesIgnore: * stays in one segment, ** crosses segments", () => {
+  assert.deepEqual(
+    [
+      matchesIgnore("assistants", "legacy-a", ["assistants/legacy-*"]),
+      matchesIgnore("assistants", "team/legacy-a", ["assistants/legacy-*"]),
+      matchesIgnore("assistants", "team/legacy-a", ["assistants/**"]),
+      matchesIgnore("assistants", "a.b", ["assistants/a?b"]),
+      matchesIgnore("assistants", "anything", []),
+    ],
+    ["assistants/legacy-*", null, "assistants/**", "assistants/a?b", null],
+  );
+});
+
+test("orgResourcesRead reads every type for one org and applies its .vapi-ignore", async () => {
+  const root = fixture({
+    "resources/acme/.vapi-ignore": "assistants/legacy-*\n",
+    "resources/acme/assistants/main.md": "---\nname: Main\n---\nHello\n",
+    "resources/acme/assistants/legacy-old.yml": "name: Old\n",
+    "resources/acme/tools/lookup.yml": "type: function\n",
+    "resources/acme/simulations/suites/core.yml": "name: Core\n",
+    "resources/other/tools/elsewhere.yml": "type: endCall\n",
+  });
+  try {
+    const resources = await silenced(() => orgResourcesRead(root, "acme"));
+    assert.deepEqual(
+      [...resources.entries()].map(([key, value]) => [
+        key,
+        value.type,
+        value.id,
+      ]),
+      [
+        ["tools:lookup", "tools", "lookup"],
+        ["assistants:main", "assistants", "main"],
+        ["simulationSuites:core", "simulationSuites", "core"],
+      ],
+    );
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("orgResourcesRead lets the caller override the ignore patterns", async () => {
+  const root = fixture({
+    "resources/acme/.vapi-ignore": "assistants/**\n",
+    "resources/acme/assistants/main.yml": "name: Main\n",
+  });
+  try {
+    const resources = await silenced(() =>
+      orgResourcesRead(root, "acme", { ignorePatterns: [] }),
+    );
+    assert.deepEqual([...resources.keys()], ["assistants:main"]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});