@@ -321,6 +321,8 @@ For changes under `src/`, `tests/` or `.github/`:
   table in the same change.
 - Changing an example under `examples/`? Doc snippets that start with
   `# examples/<path>` must match the file exactly (`npm test` checks).
+- Every request to the Vapi API sends `"User-Agent": userAgentGet()` from
+  `src/user-agent.ts`; `npm test` fails on a `fetch` without it.
 - Commit messages follow Conventional Commits (`fix(pull): …`, `docs: …`).
 - When you hit engine friction ("this should be better"), add or update an
   entry in `improvements.md` in the same change. Upstream's log collects
 
@@ -145,6 +145,17 @@ Tracks resource ID ↔ Vapi UUID mappings per org:
 
 Every resource type has a section. Keys are sorted, so diffs stay readable.
 
+## What Vapi sees
+
+Every API request uses the org's private key and identifies the tool with a
+User-Agent: `vapi-gitops-<command>/<version>`, where `<command>` is the gitops
+command you ran (`apply`, `push`, `pull`, …; `cli` if it can't be told). It
+adds ` (ci)` when `GITHUB_ACTIONS=true` or `CI` is set to anything other than
+`false` or `0`. For example, `npm run apply` in a GitHub workflow sends
+`vapi-gitops-apply/1.0.0 (ci)`. Your own npm script names are never sent.
+Vapi uses it to count how the tool is used. Nothing else is sent beyond the
+requests themselves; there is no separate telemetry.
+
 ## Where things live
 
 | Path | What it is |
 
@@ -23,7 +23,7 @@
     "rollback": "tsx src/rollback-cmd.ts",
     "promote": "tsx src/promote-cmd.ts",
     "build": "tsc --noEmit",
-    "test": "node --import tsx --test tests/*.test.ts"
+    "test": "node --import tsx --import ./tests/no-vapi-api.ts --test tests/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
 
@@ -1,5 +1,6 @@
 import { DRY_RUN, VAPI_BASE_URL, VAPI_TOKEN } from "./config.ts";
 import type { VapiResponse } from "./types.ts";
+import { userAgentGet } from "./user-agent.ts";
 import {
   INITIAL_DELAY_MS,
   MAX_RETRIES,
@@ -97,6 +98,7 @@ export async function vapiRequest<T = VapiResponse>(
       headers: {
         "Content-Type": "application/json",
         Authorization: `Bearer ${VAPI_TOKEN}`,
+        "User-Agent": userAgentGet(),
       },
       body: JSON.stringify(body),
     });
@@ -140,6 +142,7 @@ export async function vapiGet<T = unknown>(endpoint: string): Promise<T> {
       method: "GET",
       headers: {
         Authorization: `Bearer ${VAPI_TOKEN}`,
+        "User-Agent": userAgentGet(),
       },
     });
 
@@ -188,6 +191,7 @@ export async function vapiDelete(endpoint: string): Promise<void> {
       method: "DELETE",
       headers: {
         Authorization: `Bearer ${VAPI_TOKEN}`,
+        "User-Agent": userAgentGet(),
       },
     });
 
 
@@ -2,6 +2,8 @@ import { execSync } from "child_process";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { assertStateMigrated } from "./migrate-hash-store.ts";
+// Pins this command's User-Agent label for the pull and push it spawns.
+import "./user-agent.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Apply: Pull → Merge → Push (safe bidirectional sync)
 
@@ -6,6 +6,7 @@ import { dirname, join, resolve } from "path";
 import * as readline from "readline";
 import { fileURLToPath } from "url";
 import type { Environment, StateFile } from "./types.ts";
+import { userAgentGet } from "./user-agent.ts";
 
 const require = createRequire(import.meta.url);
 
@@ -362,6 +363,7 @@ async function createCall(
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.token}`,
+      "User-Agent": userAgentGet(),
     },
     body: JSON.stringify(body),
   });
 
@@ -5,6 +5,8 @@
 // `Vapi Evals` (a stable, documented name) is what branch protection
 // requires: per-target statuses only exist on PRs that touch a check.
 
+import { userAgentGet } from "./user-agent.ts";
+
 export const AGGREGATE_CONTEXT = "Vapi Evals";
 
 export type CommitState = "pending" | "success" | "failure" | "error";
@@ -84,6 +86,8 @@ export async function commitStatusPost(
           Accept: "application/vnd.github+json",
           "Content-Type": "application/json",
           "X-GitHub-Api-Version": "2022-11-28",
+          // GitHub asks API clients to name themselves.
+          "User-Agent": userAgentGet("check"),
         },
         body: JSON.stringify({
           context: status.context,
 
@@ -11,6 +11,7 @@ import { FOLDER_MAP } from "./resource-parse.ts";
 import { slugify } from "./slug-utils.ts";
 import { loadState } from "./state.ts";
 import type { ResourceType } from "./types.ts";
+import { userAgentGet } from "./user-agent.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Dangerous Sync - Delete everything NOT in state file
@@ -29,7 +30,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 async function vapiGet<T>(endpoint: string, debug = false): Promise<T> {
   await sleep(REQUEST_DELAY_MS);
   const response = await fetch(`${VAPI_BASE_URL}${endpoint}`, {
-    headers: { Authorization: `Bearer ${VAPI_TOKEN}` },
+    headers: {
+      Authorization: `Bearer ${VAPI_TOKEN}`,
+      "User-Agent": userAgentGet(),
+    },
   });
   if (!response.ok) {
     throw new Error(`GET ${endpoint} failed: ${response.status}`);
@@ -67,7 +71,10 @@ async function vapiDelete(endpoint: string): Promise<void> {
   await sleep(REQUEST_DELAY_MS);
   const response = await fetch(`${VAPI_BASE_URL}${endpoint}`, {
     method: "DELETE",
-    headers: { Authorization: `Bearer ${VAPI_TOKEN}` },
+    headers: {
+      Authorization: `Bearer ${VAPI_TOKEN}`,
+      "User-Agent": userAgentGet(),
+    },
   });
   if (!response.ok && response.status !== 404) {
     throw new Error(`DELETE ${endpoint} failed: ${response.status}`);
 
@@ -9,6 +9,7 @@ import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js";
 // the launcher, which runs before any org/token is selected.
 import { isBackupCopyFile } from "./slug-utils.ts";
 import type { StateFile } from "./types.ts";
+import { userAgentGet } from "./user-agent.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
@@ -223,7 +224,10 @@ async function apiGet(
 ): Promise<unknown> {
   const response = await fetch(`${baseUrl}${endpoint}`, {
     method: "GET",
-    headers: { Authorization: `Bearer ${token}` },
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "User-Agent": userAgentGet(),
+    },
   });
   if (!response.ok) {
     const text = await response.text();
 
@@ -153,7 +153,8 @@ export async function promotionGateRun(
       connectionFor: () => ({
         token: connection.token,
         baseUrl: connection.baseUrl ?? DEFAULT_BASE_URL,
-        userAgent: userAgentGet("check"),
+        // Gate runs are counted apart from PR check runs.
+        userAgent: userAgentGet("promote"),
       }),
       deadline: gateDeadline(check, Date.now()),
       signal: controller.signal,