ossclip 0.1.15 → 0.1.16

package/README.md

@@ -2,7 +2,11 @@
 
 **A local-first CLI that turns a talking-head take into a finished short.** It cuts silence and filler words, writes word-timed kinetic captions, frames on the measured face, and has an LLM plan **code-rendered on-screen graphics** — title cards, stat cards, diagrams, terminal and chat mockups — from what was actually said.
 
-Transcription is local (whisper.cpp), rendering is local (Remotion); the only network calls are the LLM planning ones, on your own key or your existing Claude Code subscription. Vertical 9:16 by default, landscape 16:9 with `--aspect`.
+Transcription is local (whisper.cpp), rendering is local (Remotion); the only network calls are the LLM planning ones, on your own key or your existing Claude Code / Google Antigravity subscription. Vertical 9:16 by default, landscape 16:9 with `--aspect`.
+
+![Left: the raw take. Right: the same take after ossclip produce — cut down, reframed on the measured face, word-timed captions](https://raw.githubusercontent.com/AhsanAyaz/ossclip/main/docs/site/assets/before-after.gif)
+
+*Left: the raw take. Right: the same take after `ossclip produce` — cut down, reframed on the measured face, word-timed kinetic captions.*
 
 ![A produced frame](https://raw.githubusercontent.com/AhsanAyaz/ossclip/main/docs/site/assets/render-example.png)
 
@@ -31,6 +35,8 @@ ossclip edit "<work directory>"
 
 AI can make mistakes: the cut, the captions and every graphic are generated — review the output before publishing.
 
+**Telemetry:** ossclip sends anonymous usage events (counts, durations, provider name) — never footage, transcripts, file names or paths. Turn it off any time with `ossclip telemetry off`, `OSSCLIP_TELEMETRY=0`, or `DO_NOT_TRACK=1`. Full detail in the repo README's Telemetry section.
+
 **Full documentation, flags, keybinds and the findings log:** [github.com/AhsanAyaz/ossclip](https://github.com/AhsanAyaz/ossclip)
 
 ## Licence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Local-first CLI video producer: cuts silence and fillers, word-timed captions, face-aware framing, and LLM-planned code-rendered graphics — transcription and rendering never leave your machine",
   "type": "module",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/core": "0.1.15",
-    "@ossclip/renderer": "0.1.15",
-    "@ossclip/scenes": "0.1.15"
+    "@ossclip/core": "0.1.16",
+    "@ossclip/renderer": "0.1.16",
+    "@ossclip/scenes": "0.1.16"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/doctor.ts

@@ -144,27 +144,36 @@ export async function runDoctor(cfg: OssclipConfig, p: DoctorProbes): Promise<Do
         }),
   });
 
-  // Provider, in the same order auto-detection uses (gemini → claude →
-  // claude-cli). Needed for --produce only — the cut+captions path never
-  // touches an LLM — but doctor's contract is "ready for the whole thing".
-  const provider = p.env.GEMINI_API_KEY
-    ? "gemini (GEMINI_API_KEY is set)"
-    : p.env.ANTHROPIC_API_KEY
-      ? "claude (ANTHROPIC_API_KEY is set)"
-      : (await p.binRuns("claude", "--version"))
-        ? "claude-cli (logged-in Claude Code)"
-        : null;
+  // Provider, in the same order auto-detection uses (agy → claude CLI →
+  // gemini key → anthropic key): subscription CLIs beat ambient env keys
+  // since 2026-08 — a logged-in CLI is an explicit, already-paid choice
+  // (FINDINGS §132, antigravity provider). Bin overrides are honored so
+  // doctor probes the same binary produce would spawn. Needed for --produce
+  // only — the cut+captions path never touches an LLM — but doctor's
+  // contract is "ready for the whole thing".
+  const provider = (await p.binRuns(p.env.OSSCLIP_AGY_BIN ?? "agy", "--version"))
+    ? "antigravity (agy CLI on PATH)"
+    : (await p.binRuns(p.env.OSSCLIP_CLAUDE_BIN ?? "claude", "--version"))
+      ? "claude-cli (logged-in Claude Code)"
+      : p.env.GEMINI_API_KEY
+        ? "gemini (GEMINI_API_KEY is set)"
+        : p.env.ANTHROPIC_API_KEY
+          ? "claude (ANTHROPIC_API_KEY is set)"
+          : null;
   checks.push({
     name: "LLM provider",
     ok: provider !== null,
-    detail: provider ?? "no key set and no claude CLI on PATH — needed for --produce; cut+captions works without",
+    detail:
+      provider ??
+      "no agy or claude CLI on PATH and no key set — needed for --produce; cut+captions works without",
     ...(provider !== null
       ? {}
       : {
           fix:
             "run `ossclip setup` (it can save a key for you), or " +
             "export ANTHROPIC_API_KEY or GEMINI_API_KEY (a .env file works — see README), " +
-            "or install Claude Code (https://claude.com/claude-code) and log in",
+            "or install Claude Code (https://claude.com/claude-code) and log in, " +
+            "or install Google Antigravity (https://antigravity.google) and log in",
         }),
   });
 

package/src/interactive/produce-argv.ts

@@ -1,3 +1,5 @@
+import type { ProviderName } from "@ossclip/core";
+
 /**
  * Wizard answers → the argv a user could have typed.
  *
@@ -24,7 +26,10 @@ export interface ProduceExtras {
    * the positive `--captions` stays flags-only — it exists for replay
    * pinning, and emitting it here would restate the default. */
   captions?: boolean;
-  llm?: "claude" | "claude-cli" | "gemini" | "mock";
+  /** core's ProviderName, not an inline union — a provider added there must
+   * not be silently unofferable here (the pre-§132 union had already
+   * drifted: it never listed "antigravity"). */
+  llm?: ProviderName;
 }
 
 export interface ProduceAnswers {

package/src/interactive/produce-wizard.ts

@@ -310,6 +310,9 @@ export async function produceWizard(
       await select({
         message: "LLM provider",
         options: [
+          // Listed in auto-detection's own order (FINDINGS §132): the menu
+          // teaching a different ranking than a bare run uses would be drift.
+          { value: "antigravity", label: "antigravity", hint: "your logged-in Google Antigravity (agy), no API charges" },
           { value: "claude-cli", label: "claude-cli", hint: "your logged-in Claude Code, no API charges" },
           { value: "claude", label: "claude", hint: "needs ANTHROPIC_API_KEY" },
           { value: "gemini", label: "gemini", hint: "needs GEMINI_API_KEY" },

package/src/llm-detect.ts

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+import type { ProviderName } from "@ossclip/core";
+
+/**
+ * Provider auto-detection helpers (FINDINGS §132, antigravity provider):
+ * `binOnPath` is the real `hasBin` the CLI injects into core's
+ * `defaultProviderName`, and `detectionLine` is the one place the "which
+ * provider and why" message lives — pure, total over every ProviderName, so
+ * the drift test can pin all five lines. The old inline ternary in produce.ts
+ * covered only two providers and printed the ANTHROPIC line for a
+ * gemini-detected run.
+ */
+
+/**
+ * Is this binary reachable? Sync, and a PATH scan with `existsSync` rather
+ * than a `spawnSync(bin, ["--version"])` probe: this runs on produce's
+ * startup path, and spawning agy + claude just to detect them costs
+ * ~100ms × 2 on every run. Existence-not-runnability is the same trade
+ * doctor's `binRuns` makes in the other direction — doctor is diagnostics
+ * and can afford the spawn; startup can't.
+ */
+export function binOnPath(
+  bin: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  // A path-ish override (OSSCLIP_AGY_BIN=/opt/agy) names a file, not a PATH
+  // entry — check it verbatim. `\` counts on win32 only; it is a legal
+  // filename character on posix.
+  if (bin.includes("/") || (platform === "win32" && bin.includes("\\"))) {
+    return existsSync(bin);
+  }
+  const pathEntries = (env.PATH ?? "").split(delimiter).filter(Boolean);
+  // On Windows a bare `agy` resolves through PATHEXT (agy.cmd, agy.exe…);
+  // the extensionless name is still tried first for shims that have none.
+  const suffixes =
+    platform === "win32"
+      ? ["", ...(env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)]
+      : [""];
+  return pathEntries.some((dir) => suffixes.some((ext) => existsSync(join(dir, bin + ext))));
+}
+
+/**
+ * The "▸ which provider and why" line for an auto-detected run. Each line
+ * names its own trigger so a surprised user can see exactly which check won
+ * — the point of the §132 order change is visible, not silent.
+ */
+export function detectionLine(name: ProviderName): string {
+  switch (name) {
+    case "antigravity":
+      return "▸ agy CLI found — using Google Antigravity (subscription auth)";
+    case "claude-cli":
+      return "▸ using the Claude Code CLI (subscription auth)";
+    case "gemini":
+      return "▸ GEMINI_API_KEY found — using the Gemini API";
+    case "claude":
+      return "▸ ANTHROPIC_API_KEY found — using the Claude API";
+    case "mock":
+      return "▸ using the mock provider (no LLM)";
+  }
+}

package/src/produce.ts

@@ -98,6 +98,7 @@ import {
   type Transcript,
 } from "@ossclip/core";
 import { recordRecentProject } from "./edit";
+import { binOnPath, detectionLine } from "./llm-detect";
 import {
   strandedOverrideSiblings,
   strandedPointerLine,
@@ -122,6 +123,16 @@ export interface ProduceResult {
   workdir: string;
   out?: string;
   rendered: boolean;
+  /**
+   * Telemetry inputs (FINDINGS §134), surfaced here so the command layer can
+   * build the event without produce() knowing telemetry exists. The duration
+   * is only ever SENT as a bucket, and the provider is the resolved NAME —
+   * never a key, never a path.
+   */
+  sourceDurationSec: number;
+  sceneCount: number;
+  /** Resolved provider name when the LLM ran; undefined without --produce. */
+  llmProvider?: string;
 }
 
 /**
@@ -848,16 +859,16 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // LLM ran. Everything downstream that a viewer READS — captions, scene copy,
   // the grounding check — uses the repaired transcript instead, so a
   // mishearing can't reach the screen twice in two different spellings.
-  const providerName = opts.provider ?? defaultProviderName();
+  const providerName = opts.provider ?? defaultProviderName(process.env, binOnPath);
   let provider: LlmProvider | null = null;
   const needsLlm = opts.produce === true;
   if (needsLlm) {
+    // Only when auto-detected: a typed --llm needs no explanation. The line
+    // itself lives in llm-detect.ts so a drift test covers every provider —
+    // the inline ternary this replaces printed the ANTHROPIC line for a
+    // gemini-detected run (FINDINGS §132, antigravity provider).
     if (!opts.provider) {
-      console.log(
-        providerName === "claude-cli"
-          ? "▸ no ANTHROPIC_API_KEY — using the Claude Code CLI (subscription auth)"
-          : "▸ ANTHROPIC_API_KEY found — using the Claude API",
-      );
+      console.log(detectionLine(providerName));
     }
     provider = createTieredProvider(providerName, {
       model: opts.llmModel,
@@ -2196,7 +2207,13 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   if (!opts.render) {
     console.log(`▸ skipping render (--no-render). Props at ${join(work, "render-props.json")}`);
     console.log(editHint(work));
-    return { workdir: work, rendered: false };
+    return {
+      workdir: work,
+      rendered: false,
+      sourceDurationSec: sourceProbe.duration,
+      sceneCount: scenes.length,
+      llmProvider: provider ? providerName : undefined,
+    };
   }
 
   const outPath = resolve(opts.out ?? defaultOutPath(originalInput));
@@ -2379,5 +2396,12 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   await recordRecentProject(work);
   console.log(`✓ done → ${outPath}`);
   console.log(editHint(work));
-  return { workdir: work, out: outPath, rendered: true };
+  return {
+    workdir: work,
+    out: outPath,
+    rendered: true,
+    sourceDurationSec: sourceProbe.duration,
+    sceneCount: scenes.length,
+    llmProvider: provider ? providerName : undefined,
+  };
 }

package/src/program.ts

@@ -8,6 +8,14 @@ import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { produce } from "./produce";
 import { setReplayArgv } from "./replay-argv";
+import {
+  bootstrapTelemetry,
+  durationBucket,
+  loadState,
+  maybeAskRating,
+  saveState,
+  telemetryOffReason,
+} from "./telemetry";
 
 // Before anything reads a provider key (R16 §77) — including the auto-detect
 // order in `defaultProviderName`, which decides which model runs.
@@ -30,6 +38,12 @@ const envFiles = loadEnvFiles();
 export function buildProgram(): Command {
   const program = new Command();
 
+  // Before dispatch, so the one-time first-run notice precedes any command's
+  // own output. Inert in this repo's tests by construction: while POSTHOG_KEY
+  // is the placeholder, bootstrap touches no disk and sends nothing (FINDINGS
+  // §134) — which is what lets every test build the real program unmocked.
+  const telemetry = bootstrapTelemetry();
+
   program
     .name("ossclip")
     .description(
@@ -215,9 +229,13 @@ export function buildProgram(): Command {
       // Must state `defaultProviderName`'s real order — the old text omitted
       // the GEMINI-first branch and promised claude-first (field report
       // 2026-08-07); the drift test in llm-help.test.ts pins the agreement.
-      "claude | claude-cli | gemini | mock. Default: gemini if GEMINI_API_KEY is set, " +
-        "else claude if ANTHROPIC_API_KEY is set, else claude-cli (your logged-in " +
-        "Claude Code — Pro/Max subscription, no API charges)",
+      // Order changed 2026-08: subscription CLIs beat ambient env keys
+      // (FINDINGS §132, antigravity provider).
+      "antigravity | claude | claude-cli | gemini | mock. Default: antigravity if the agy " +
+        "CLI is installed (your logged-in Google Antigravity, no API charges), else " +
+        "claude-cli if the claude CLI is installed (your logged-in Claude Code — Pro/Max " +
+        "subscription, no API charges), else gemini if GEMINI_API_KEY is set, else claude " +
+        "if ANTHROPIC_API_KEY is set, else claude-cli",
     )
     .option("--llm-model <id>", "override the provider's default model")
     .option(
@@ -337,7 +355,7 @@ export function buildProgram(): Command {
       if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
       const cleanup = CleanupLevelSchema.parse(opts.cleanup);
       const provider = opts.llm
-        ? z.enum(["claude", "claude-cli", "gemini", "mock"]).parse(opts.llm)
+        ? z.enum(["antigravity", "claude", "claude-cli", "gemini", "mock"]).parse(opts.llm)
         : undefined;
       const forceComponent = opts.forceComponent
         ? SceneComponentIdSchema.parse(opts.forceComponent)
@@ -360,46 +378,86 @@ export function buildProgram(): Command {
         opts.whisperLanguage !== undefined
           ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
           : undefined;
-      const result = await produce(input, {
-        out: opts.out,
-        cleanup,
-        transcript: opts.transcript,
-        render: opts.render,
-        mezzanine: opts.mezzanine,
-        workdir: opts.workdir,
-        sort,
-        sortExplicit,
-        aspect: opts.aspect === "16:9" ? "16:9" : "9:16",
-        noiseDb: opts.noiseDb,
-        produce: opts.produce,
-        intent: opts.intent,
-        provider,
-        llmModel: opts.llmModel,
-        llmFastModel: opts.llmFastModel,
-        speaker: opts.speaker,
-        scenes: opts.scenes,
-        repair: opts.repair,
-        whisperModel: opts.whisperModel,
-        whisperLanguage,
-        forceComponent,
-        // commander gives `--no-cover` as cover:false and `--cover <path>` as a
-        // string on the same key.
-        sourceIsEdited: opts.sourceIsEdited === true,
-        blooperMarker: opts.blooperMarker,
-        collapseRetakes: opts.collapseRetakes,
-        sourceFit,
-        // undefined = "not typed", so produce can let the config decide.
-        watermark: opts.watermark,
-        // undefined = "not typed" here too — the default (ON) is applied at
-        // the pin site, not coerced in transit.
-        captions: opts.captions,
-        cover: opts.cover !== false,
-        coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
-        clip: opts.clip,
-        clipWindow: opts.clipWindow,
-      });
-      const { offerEditor } = await import("./interactive/offer-editor");
-      await offerEditor(result, { flag: opts.openEditor, port: opts.editorPort });
+      // Wall clock around produce() only — the editor offer below can sit at
+      // an interactive prompt for as long as the user thinks, and think-time
+      // would poison the duration metric (FINDINGS §134).
+      const startedMs = Date.now();
+      try {
+        const result = await produce(input, {
+          out: opts.out,
+          cleanup,
+          transcript: opts.transcript,
+          render: opts.render,
+          mezzanine: opts.mezzanine,
+          workdir: opts.workdir,
+          sort,
+          sortExplicit,
+          aspect: opts.aspect === "16:9" ? "16:9" : "9:16",
+          noiseDb: opts.noiseDb,
+          produce: opts.produce,
+          intent: opts.intent,
+          provider,
+          llmModel: opts.llmModel,
+          llmFastModel: opts.llmFastModel,
+          speaker: opts.speaker,
+          scenes: opts.scenes,
+          repair: opts.repair,
+          whisperModel: opts.whisperModel,
+          whisperLanguage,
+          forceComponent,
+          // commander gives `--no-cover` as cover:false and `--cover <path>` as a
+          // string on the same key.
+          sourceIsEdited: opts.sourceIsEdited === true,
+          blooperMarker: opts.blooperMarker,
+          collapseRetakes: opts.collapseRetakes,
+          sourceFit,
+          // undefined = "not typed", so produce can let the config decide.
+          watermark: opts.watermark,
+          // undefined = "not typed" here too — the default (ON) is applied at
+          // the pin site, not coerced in transit.
+          captions: opts.captions,
+          cover: opts.cover !== false,
+          coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
+          clip: opts.clip,
+          clipWindow: opts.clipWindow,
+        });
+        // Counts, buckets and names only — the duration crosses the wire as a
+        // bucket, and nothing here can carry a path (assertSafeProps enforces
+        // it). Inert while POSTHOG_KEY is the placeholder (FINDINGS §134).
+        telemetry.record("produce_completed", {
+          duration_ms: Date.now() - startedMs,
+          llm_provider: result.llmProvider ?? "none",
+          produced: opts.produce === true,
+          aspect: opts.aspect === "16:9" ? "16:9" : "9:16",
+          clip: opts.clip !== undefined,
+          render: opts.render !== false,
+          source_duration_bucket: durationBucket(result.sourceDurationSec),
+          scenes: result.sceneCount,
+        });
+        if (!telemetry.disabled) {
+          telemetry.state.produceCount += 1;
+          try {
+            saveState(telemetry.state);
+          } catch {
+            // A read-only home dir must never fail the produce that just
+            // succeeded — the rating gate simply advances a run later.
+          }
+        }
+        const { offerEditor } = await import("./interactive/offer-editor");
+        await offerEditor(result, { flag: opts.openEditor, port: opts.editorPort });
+        // Deliberately LAST — after the render summary and the editor offer —
+        // so the one question ossclip ever asks is the last thing on screen.
+        await maybeAskRating(telemetry);
+      } catch (err) {
+        // The constructor NAME only, never the message: error messages
+        // routinely quote the input path, the exact thing §134 forbids.
+        telemetry.record("produce_failed", {
+          error_class: err instanceof Error ? err.constructor.name : "NonError",
+        });
+        throw err;
+      } finally {
+        await telemetry.flush();
+      }
     });
 
   program
@@ -417,7 +475,7 @@ export function buildProgram(): Command {
     )
     .action(async (input: string, opts) => {
       const cleanup = CleanupLevelSchema.parse(opts.cleanup);
-      await produce(input, {
+      const result = await produce(input, {
         cleanup,
         transcript: opts.transcript,
         render: false,
@@ -431,6 +489,11 @@ export function buildProgram(): Command {
             ? z.string().trim().min(1, "--whisper-language needs a code, e.g. ur").parse(opts.whisperLanguage)
             : undefined,
       });
+      telemetry.record("transcribe_completed", {
+        cleanup_level: cleanup,
+        source_duration_bucket: durationBucket(result.sourceDurationSec),
+      });
+      await telemetry.flush();
     });
 
   program
@@ -530,6 +593,11 @@ export function buildProgram(): Command {
         const { openInBrowser } = await import("./open");
         openInBrowser(server.url);
       }
+      // Fire-and-forget on purpose: the server keeps the process alive for
+      // the request's lifetime, and awaiting here would put a metrics POST
+      // between the user and their browser opening (FINDINGS §134).
+      telemetry.record("editor_opened", {});
+      void telemetry.flush();
     });
 
   program
@@ -545,7 +613,13 @@ export function buildProgram(): Command {
     .action(async (opts) => {
       if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
       const { setup } = await import("./setup/setup");
-      await setup({ model: opts.model, skipLlm: opts.skipLlm, force: opts.force, yes: opts.yes });
+      const summary = await setup({ model: opts.model, skipLlm: opts.skipLlm, force: opts.force, yes: opts.yes });
+      telemetry.record("setup_completed", {
+        steps_total: summary.stepsTotal,
+        steps_satisfied: summary.stepsSatisfied,
+        steps_failed: summary.stepsFailed,
+      });
+      await telemetry.flush();
     });
 
   program
@@ -560,8 +634,61 @@ export function buildProgram(): Command {
       const { loadConfig } = await import("@ossclip/core");
       const checks = await runDoctor(loadConfig(), realProbes(resolveEditorPageDir()));
       console.log(formatDoctor(checks));
+      const passedCount = checks.filter((c) => c.ok).length;
+      telemetry.record("doctor_run", {
+        checks_total: checks.length,
+        checks_passed: passedCount,
+        checks_failed: checks.length - passedCount,
+      });
+      await telemetry.flush();
       if (checks.some((c) => !c.ok)) process.exit(1);
     });
 
+  program
+    .command("telemetry")
+    .description("show or change anonymous usage telemetry — on | off | status")
+    .argument("[action]", "on | off | status (default: status)")
+    .action(async (action: string | undefined) => {
+      // Parsed, not coerced (§93a shape): `ossclip telemetry offf` must be a
+      // loud error naming the typo, never a silent status print.
+      const parsed = z.enum(["on", "off", "status"]).parse(action ?? "status");
+      // A fresh load, not the bootstrap instance's state: with the
+      // placeholder key bootstrap never reads the file, but an EXPLICIT
+      // on/off is the user asking for a persisted preference — it must land
+      // in ~/.ossclip/telemetry.json either way, ready for a keyed build.
+      const state = loadState();
+      if (parsed === "off") {
+        state.enabled = false;
+        saveState(state);
+        console.log("✓ telemetry off — nothing will be sent (saved in ~/.ossclip/telemetry.json)");
+        return;
+      }
+      if (parsed === "on") {
+        state.enabled = true;
+        saveState(state);
+        console.log(
+          "✓ telemetry on — anonymous usage events only; see the README's Telemetry section",
+        );
+        return;
+      }
+      const reason = telemetryOffReason(process.env, state);
+      if (reason === null) {
+        console.log("telemetry: enabled (anonymous usage events only)");
+      } else {
+        // Name the switch that WON, not just the state — three different
+        // offs (env, standard env, config) all look identical otherwise, and
+        // "why is it still off?" needs the answer.
+        const why: Record<typeof reason, string> = {
+          "placeholder-key":
+            "this build ships without a telemetry key — nothing is ever sent or stored",
+          env: `OSSCLIP_TELEMETRY=${process.env.OSSCLIP_TELEMETRY} in the environment`,
+          "do-not-track": `DO_NOT_TRACK=${process.env.DO_NOT_TRACK} in the environment`,
+          config: "`ossclip telemetry off` (saved in ~/.ossclip/telemetry.json)",
+        };
+        console.log(`telemetry: disabled — ${why[reason]}`);
+      }
+      console.log(`anonymous id: ${state.anonymousId}`);
+    });
+
   return program;
 }

package/src/setup/plan.ts

@@ -161,15 +161,19 @@ export async function planSetup(
     });
   }
 
-  // Provider, in doctor's detection order. Setup can save a key, but only
-  // ever interactively — never invented, never required (--skip-llm).
-  const provider = p.env.GEMINI_API_KEY
-    ? "gemini (GEMINI_API_KEY is set)"
-    : p.env.ANTHROPIC_API_KEY
-      ? "claude (ANTHROPIC_API_KEY is set)"
-      : (await p.binRuns("claude", "--version"))
-        ? "claude-cli (logged-in Claude Code)"
-        : null;
+  // Provider, in doctor's detection order (agy → claude CLI → gemini key →
+  // anthropic key; subscription CLIs beat ambient keys — FINDINGS §132,
+  // antigravity provider). Setup can save a key, but only ever
+  // interactively — never invented, never required (--skip-llm).
+  const provider = (await p.binRuns(p.env.OSSCLIP_AGY_BIN ?? "agy", "--version"))
+    ? "antigravity (agy CLI on PATH)"
+    : (await p.binRuns(p.env.OSSCLIP_CLAUDE_BIN ?? "claude", "--version"))
+      ? "claude-cli (logged-in Claude Code)"
+      : p.env.GEMINI_API_KEY
+        ? "gemini (GEMINI_API_KEY is set)"
+        : p.env.ANTHROPIC_API_KEY
+          ? "claude (ANTHROPIC_API_KEY is set)"
+          : null;
   if (opts.skipLlm) {
     steps.push({
       kind: "provider",

package/src/setup/provider.ts

@@ -23,12 +23,17 @@ export async function promptForProvider(io: ProviderIO, configDir: string): Prom
   io.say("  1) I have an Anthropic API key");
   io.say("  2) I have a Google Gemini API key");
   io.say("  3) I use Claude Code (already logged in — no key needed)");
+  io.say("  4) I use Google Antigravity (agy — already logged in, no key needed)");
   io.say("  Enter) skip for now");
   const choice = (await io.ask("Choice: ")).trim();
   if (choice === "3") {
     io.say("▸ nothing to save — ossclip finds the claude CLI on PATH by itself.");
     return;
   }
+  if (choice === "4") {
+    io.say("▸ nothing to save — ossclip finds the agy CLI on PATH by itself.");
+    return;
+  }
   const envKey = choice === "1" ? "ANTHROPIC_API_KEY" : choice === "2" ? "GEMINI_API_KEY" : null;
   if (!envKey) {
     io.say("▸ skipped — `ossclip doctor` will remind you what --produce needs.");

package/src/setup/setup.ts

@@ -38,7 +38,9 @@ const probeBin = (bin: string, arg: string): Promise<boolean> =>
     child.on("exit", () => resolve(true));
   });
 
-export async function setup(opts: SetupCliOptions): Promise<void> {
+export async function setup(
+  opts: SetupCliOptions,
+): Promise<{ stepsTotal: number; stepsSatisfied: number; stepsFailed: number }> {
   const cfg = loadConfig();
   const model = opts.model ?? cfg.model;
   const probes: SetupProbes = {
@@ -70,7 +72,7 @@ export async function setup(opts: SetupCliOptions): Promise<void> {
       const answer = (await rl.question("Proceed? [Y/n] ")).trim().toLowerCase();
       if (answer === "n" || answer === "no") {
         console.log("▸ nothing changed.");
-        return;
+        return { stepsTotal: steps.length, stepsSatisfied: 0, stepsFailed: 0 };
       }
     }
 
@@ -157,7 +159,8 @@ export async function setup(opts: SetupCliOptions): Promise<void> {
           } else if (step.status === "prompt") {
             console.log(
               "▸ no LLM provider configured (non-interactive run) — needed for --produce only; " +
-                "set ANTHROPIC_API_KEY or GEMINI_API_KEY when you want it.",
+                "a logged-in Claude Code or Google Antigravity (agy) CLI is picked up automatically, " +
+                "or set ANTHROPIC_API_KEY or GEMINI_API_KEY when you want it.",
             );
           }
           break;
@@ -179,6 +182,13 @@ export async function setup(opts: SetupCliOptions): Promise<void> {
   const checks = await runDoctor(loadConfig(), realProbes(resolveEditorPageDir()));
   console.log(formatDoctor(checks));
   if (failures.length > 0) process.exitCode = 1;
+  // The caller (program.ts) owns telemetry; this module stays network-free
+  // beyond its own downloads. It just reports what happened.
+  return {
+    stepsTotal: steps.length,
+    stepsSatisfied: steps.filter((s) => s.status === "satisfied").length,
+    stepsFailed: failures.length,
+  };
 }
 
 /** Download an asset (with resume) and extract it under the managed bin dir. */

package/src/telemetry.ts

@@ -0,0 +1,468 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod/v4";
+import { CONFIG_DIR } from "@ossclip/core";
+
+/**
+ * Anonymous opt-out usage telemetry (FINDINGS §134).
+ *
+ * The layering follows the house split: everything above the "I/O" divider is
+ * pure — testable without a filesystem, a TTY or a network — and the thin I/O
+ * below it (state file, PostHog POST, readline) is injectable where a test
+ * needs to see through it.
+ *
+ * Privacy floor, non-negotiable: no event ever carries a file path, a file
+ * name, transcript text, `--intent` text, a prompt, or a key. `assertSafeProps`
+ * is the drift guard that keeps FUTURE events honest about it, not just the
+ * ones written today.
+ */
+
+/**
+ * The baked-in default is the project's WRITE-ONLY ingest key — public by
+ * design (every shipped analytics client carries one; it can only capture,
+ * never read), and baked rather than env-read because ossclip is a
+ * distributed CLI: an end user who installed from npm has no POSTHOG_API_KEY
+ * in their environment, so an env-only key would mean telemetry that never
+ * reports from exactly the machines it exists to count (§134). The env var
+ * still OVERRIDES the default for development against another project.
+ *
+ * With the key real, the test suite's hermeticity comes from vitest.config.ts
+ * exporting OSSCLIP_TELEMETRY=0 into every test process — see the
+ * hermetic-suite tests in telemetry.test.ts. Typed `string`, not the literal,
+ * so the `=== POSTHOG_PLACEHOLDER` checks stay ordinary comparisons.
+ */
+export const POSTHOG_PLACEHOLDER = "phc_REPLACE_ME";
+export const POSTHOG_KEY: string =
+  process.env.POSTHOG_API_KEY ?? "phc_B8y7hMMmHYVEmkUfiLfuBcWoWM5GjbnaT9oBZLZnyPB3";
+export const POSTHOG_HOST: string = process.env.POSTHOG_HOST ?? "https://eu.i.posthog.com";
+
+/**
+ * The whole latency budget telemetry is allowed to cost a run: one POST,
+ * aborted at this cap, no retries (§134). A metrics request must never be
+ * the slowest part of somebody's render.
+ */
+export const FLUSH_TIMEOUT_MS = 2500;
+
+// ---------------------------------------------------------------------------
+// Pure
+// ---------------------------------------------------------------------------
+
+const freshDefaults = () => ({
+  anonymousId: randomUUID(),
+  enabled: true,
+  noticeShown: false,
+  produceCount: 0,
+  ratingAsked: 0,
+  ratingDone: false,
+});
+
+/**
+ * Per-field `.catch` so a hand-edited or truncated telemetry.json degrades a
+ * FIELD at a time (a corrupt `enabled` must not throw away the anonymousId),
+ * and an outer `.catch` so a document that isn't even an object resets whole
+ * — a corrupt state file must never crash the CLI it is riding in.
+ */
+export const TelemetryStateSchema = z
+  .object({
+    anonymousId: z.string().min(1).catch(() => randomUUID()),
+    enabled: z.boolean().catch(true),
+    noticeShown: z.boolean().catch(false),
+    produceCount: z.number().int().min(0).catch(0),
+    ratingAsked: z.number().int().min(0).catch(0),
+    ratingDone: z.boolean().catch(false),
+  })
+  .catch(freshDefaults);
+export type TelemetryState = z.infer<typeof TelemetryStateSchema>;
+
+export function defaultTelemetryState(): TelemetryState {
+  return freshDefaults();
+}
+
+export type TelemetryOffReason = "placeholder-key" | "env" | "do-not-track" | "config";
+
+/**
+ * Why telemetry is off, or null when it is on. Precedence, most global first:
+ * a keyless build can never send (§134's hard-off invariant), an exported env
+ * var is the user's word in THIS shell, DO_NOT_TRACK is the ecosystem-wide
+ * spelling of the same word, and the config file is the persisted preference.
+ * The reason (not just the boolean) exists for `ossclip telemetry status`,
+ * which must name the switch that won.
+ */
+export function telemetryOffReason(
+  env: NodeJS.ProcessEnv,
+  state: { enabled: boolean },
+  apiKey: string = POSTHOG_KEY,
+): TelemetryOffReason | null {
+  if (apiKey === POSTHOG_PLACEHOLDER) return "placeholder-key";
+  if (["0", "false", "off"].includes(env.OSSCLIP_TELEMETRY ?? "")) return "env";
+  if (["1", "true"].includes(env.DO_NOT_TRACK ?? "")) return "do-not-track";
+  if (state.enabled === false) return "config";
+  return null;
+}
+
+export function telemetryDisabled(
+  env: NodeJS.ProcessEnv,
+  state: { enabled: boolean },
+  apiKey: string = POSTHOG_KEY,
+): boolean {
+  return telemetryOffReason(env, state, apiKey) !== null;
+}
+
+/**
+ * Substrings no event prop key may contain, case-insensitively. This is the
+ * privacy promise as code: a future `source_path` or `intentText` prop fails
+ * loudly in the unit tests instead of quietly shipping user data. "text" and
+ * "hook" cover the producer's copy fields; "key" covers credentials.
+ */
+export const FORBIDDEN_PROP_KEYS = [
+  "path",
+  "file",
+  "dir",
+  "transcript",
+  "intent",
+  "prompt",
+  "key",
+  "hook",
+  "text",
+] as const;
+
+export function assertSafeProps(props: Record<string, unknown>): void {
+  for (const key of Object.keys(props)) {
+    const lower = key.toLowerCase();
+    for (const forbidden of FORBIDDEN_PROP_KEYS) {
+      if (lower.includes(forbidden)) {
+        throw new Error(
+          `telemetry prop "${key}" contains forbidden substring "${forbidden}" — ` +
+            "event props must never carry paths, names, text or keys (FINDINGS §134)",
+        );
+      }
+    }
+  }
+}
+
+export interface EventContext {
+  anonymousId: string;
+  version: string;
+  platform: string;
+  arch: string;
+  nodeMajor: number;
+  ci: boolean;
+  /** Injectable for tests; production always rides POSTHOG_KEY. */
+  apiKey?: string;
+}
+
+/** The PostHog capture body — https://posthog.com/docs/api/capture */
+export interface CaptureEvent {
+  api_key: string;
+  event: string;
+  distinct_id: string;
+  timestamp: string;
+  properties: Record<string, unknown>;
+}
+
+export function buildEvent(
+  name: string,
+  props: Record<string, unknown>,
+  ctx: EventContext,
+): CaptureEvent {
+  assertSafeProps(props);
+  return {
+    api_key: ctx.apiKey ?? POSTHOG_KEY,
+    event: name,
+    distinct_id: ctx.anonymousId,
+    timestamp: new Date().toISOString(),
+    properties: {
+      ...props,
+      app_version: ctx.version,
+      os: ctx.platform,
+      arch: ctx.arch,
+      node_major: ctx.nodeMajor,
+      ci: ctx.ci,
+      // Anonymous events, never person profiles — the PostHog-side half of
+      // the anonymity promise (and the cheaper event class, incidentally).
+      $process_person_profile: false,
+    },
+  };
+}
+
+/**
+ * The exact seconds never leave the machine — a duration is close to a
+ * fingerprint of a specific take, and a bucket answers the only question we
+ * have ("short-form or long-form users?") without carrying one.
+ */
+export function durationBucket(seconds: number): "<1m" | "1-5m" | "5-15m" | ">15m" {
+  if (seconds < 60) return "<1m";
+  if (seconds <= 300) return "1-5m";
+  if (seconds <= 900) return "5-15m";
+  return ">15m";
+}
+
+/**
+ * Ask after the 3rd successful produce (someone still around at three runs
+ * has an opinion worth having), never again after an answer, and never more
+ * than twice — two Enter-skips is an answer too.
+ */
+export function shouldAskRating(state: TelemetryState): boolean {
+  return !state.ratingDone && state.ratingAsked < 2 && state.produceCount >= 3;
+}
+
+/**
+ * Parsed, not coerced (§93a shape): only a lone 1-5 counts. "3.5", "great"
+ * and "" are all a skip, never a Number()-mangled score.
+ */
+const RatingSchema = z
+  .string()
+  .trim()
+  .regex(/^[1-5]$/)
+  .transform(Number);
+
+export function parseRating(line: string): number | null {
+  const parsed = RatingSchema.safeParse(line);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * The one-time first-run notice. LOUD by design — an opt-out default is only
+ * honest if the opt-out is impossible to miss — and it states the privacy
+ * floor in the same breath.
+ */
+export const NOTICE = [
+  "▸ ossclip collects anonymous usage events — command counts, durations, the LLM",
+  "  provider name. It NEVER sends your footage, transcripts, file names, paths,",
+  "  or prompts. Turn it off any time: `ossclip telemetry off` or OSSCLIP_TELEMETRY=0.",
+  '  Details and the full event list: README, "Telemetry".',
+].join("\n");
+
+export const RATING_PROMPT = "Rate ossclip so far? 1-5, Enter to skip: ";
+
+// ---------------------------------------------------------------------------
+// I/O
+// ---------------------------------------------------------------------------
+
+export function telemetryStatePath(configDir: string = CONFIG_DIR): string {
+  return join(configDir, "telemetry.json");
+}
+
+/**
+ * Read-only: a load never writes. Persistence happens only at the explicit
+ * saveState call sites (notice shown, produce counted, rating answered,
+ * on/off toggled) — which is what lets the placeholder-key build guarantee
+ * "no state writes" by simply never reaching those sites (§134).
+ */
+export function loadState(configDir: string = CONFIG_DIR): TelemetryState {
+  let raw: string;
+  try {
+    raw = readFileSync(telemetryStatePath(configDir), "utf8");
+  } catch {
+    return defaultTelemetryState(); // no file yet — first run
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = undefined; // corrupt file → the schema's outer catch resets it
+  }
+  return TelemetryStateSchema.parse(parsed);
+}
+
+export function saveState(state: TelemetryState, configDir: string = CONFIG_DIR): void {
+  mkdirSync(configDir, { recursive: true });
+  // 0600: the anonymousId is not a secret, but a state file only its owner
+  // can read costs nothing and forecloses the question.
+  writeFileSync(telemetryStatePath(configDir), `${JSON.stringify(state, null, 2)}\n`, {
+    mode: 0o600,
+  });
+}
+
+function cliVersion(): string {
+  // Same manifest-read as program.ts's .version() (R22 §113) — a literal here
+  // would report a stale number for the life of every release after it.
+  try {
+    return (
+      JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+        version: string;
+      }
+    ).version;
+  } catch {
+    return "0.0.0";
+  }
+}
+
+function isCi(env: NodeJS.ProcessEnv): boolean {
+  return env.CI !== undefined && !["", "0", "false"].includes(env.CI);
+}
+
+/**
+ * One instance per CLI invocation. `record` buffers, `flush` sends one batch;
+ * both are internally safe — telemetry must never break, slow (beyond
+ * FLUSH_TIMEOUT_MS) or noisy-up a run, so errors are swallowed HERE rather
+ * than try/caught at every call site.
+ */
+export class Telemetry {
+  private readonly events: CaptureEvent[] = [];
+  private readonly ctx: EventContext;
+
+  constructor(
+    private readonly env: NodeJS.ProcessEnv,
+    readonly state: TelemetryState,
+    private readonly fetchImpl: typeof fetch = fetch,
+    ctx?: Partial<EventContext>,
+  ) {
+    this.ctx = {
+      anonymousId: ctx?.anonymousId ?? state.anonymousId,
+      version: ctx?.version ?? cliVersion(),
+      platform: ctx?.platform ?? process.platform,
+      arch: ctx?.arch ?? process.arch,
+      nodeMajor: ctx?.nodeMajor ?? Number.parseInt(process.versions.node, 10),
+      ci: ctx?.ci ?? isCi(env),
+      apiKey: ctx?.apiKey,
+    };
+  }
+
+  get disabled(): boolean {
+    return telemetryDisabled(this.env, this.state, this.ctx.apiKey ?? POSTHOG_KEY);
+  }
+
+  record(name: string, props: Record<string, unknown> = {}): void {
+    try {
+      if (this.disabled) return;
+      this.events.push(buildEvent(name, props, this.ctx));
+    } catch {
+      // Fail CLOSED: a prop key tripping assertSafeProps means the event
+      // would have carried something the privacy floor forbids — dropping it
+      // is the correct production outcome (no data beats wrong data), and
+      // the unit tests on buildEvent are where the throw is seen and fixed.
+    }
+  }
+
+  async flush(): Promise<void> {
+    const batch = this.events.splice(0);
+    if (batch.length === 0) return;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), FLUSH_TIMEOUT_MS);
+    try {
+      // Raced against our own abort, not just handed the signal: an injected
+      // fetch (tests) or a polyfill that ignores `signal` would otherwise
+      // hang this await past the cap — the exact promise flush exists to keep.
+      await Promise.race([
+        this.fetchImpl(`${POSTHOG_HOST}/batch/`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ api_key: this.ctx.apiKey ?? POSTHOG_KEY, batch }),
+          signal: ac.signal,
+        }),
+        new Promise<void>((resolveRace) => {
+          ac.signal.addEventListener("abort", () => resolveRace(), { once: true });
+        }),
+      ]);
+    } catch {
+      // Swallow everything — refused, offline, DNS, 4xx/5xx, abort. No
+      // retries either: a metrics batch is not worth a second attempt's
+      // latency, and the next run sends fresh events anyway.
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/** Prints the first-run notice once and persists the flag. */
+export function maybeShowNotice(
+  state: TelemetryState,
+  out: (s: string) => void,
+  configDir: string = CONFIG_DIR,
+): void {
+  if (state.noticeShown) return;
+  out(NOTICE);
+  state.noticeShown = true;
+  saveState(state, configDir);
+}
+
+/**
+ * The per-invocation entry point program.ts calls before dispatch. With the
+ * placeholder key this returns an inert instance WITHOUT touching disk —
+ * shipping keyless must be silent (§134), and it is also what keeps every
+ * `buildProgram()` in the test suite from writing ~/.ossclip.
+ */
+export function bootstrapTelemetry(
+  env: NodeJS.ProcessEnv = process.env,
+  out: (s: string) => void = console.log,
+): Telemetry {
+  if (POSTHOG_KEY === POSTHOG_PLACEHOLDER) {
+    return new Telemetry(env, defaultTelemetryState());
+  }
+  // Env-level off (OSSCLIP_TELEMETRY / DO_NOT_TRACK) returns BEFORE any disk
+  // touch: a run the user switched off must not read or create ~/.ossclip
+  // state — and it is also what keeps the test suite (which exports
+  // OSSCLIP_TELEMETRY=0 from vitest.config.ts) out of the real home dir.
+  if (telemetryDisabled(env, { enabled: true })) {
+    return new Telemetry(env, defaultTelemetryState());
+  }
+  let telemetry: Telemetry;
+  try {
+    const state = loadState();
+    telemetry = new Telemetry(env, state);
+    if (!telemetry.disabled && !state.noticeShown) {
+      maybeShowNotice(state, out);
+      // Piggybacks on noticeShown — one flag, sent exactly once. Flushed
+      // fire-and-forget because the first command may be one that never
+      // flushes itself (doctor, setup); the request rides while it runs.
+      telemetry.record("cli_first_run", {});
+      void telemetry.flush();
+    }
+  } catch {
+    // A read-only home dir or a hostile state file must never take the CLI
+    // down — telemetry degrades to inert, the run proceeds.
+    telemetry = new Telemetry(env, defaultTelemetryState());
+  }
+  return telemetry;
+}
+
+/**
+ * The one-time rating ask, AFTER the run's own output so it is the last thing
+ * on screen. TTY-only and CI-excluded: a prompt into a pipe is a hang, and a
+ * prompt at a CI log is noise. Internally safe like the class methods.
+ */
+export async function maybeAskRating(
+  telemetry: Telemetry,
+  opts: {
+    isTTY?: boolean;
+    ci?: boolean;
+    ask?: () => Promise<string | null>;
+    configDir?: string;
+  } = {},
+): Promise<void> {
+  try {
+    if (telemetry.disabled) return;
+    if (!shouldAskRating(telemetry.state)) return;
+    const tty = opts.isTTY ?? (process.stdout.isTTY === true && process.stdin.isTTY === true);
+    if (!tty) return;
+    if (opts.ci ?? isCi(process.env)) return;
+    const line = await (opts.ask ?? askRatingOnce)();
+    const score = line === null ? null : parseRating(line);
+    if (score !== null) {
+      telemetry.record("rating_submitted", { score });
+      telemetry.state.ratingDone = true;
+    } else {
+      // Empty, invalid, or timed out — all a skip; two skips end the asking.
+      telemetry.state.ratingAsked += 1;
+    }
+    saveState(telemetry.state, opts.configDir);
+  } catch {
+    // A rating prompt failing must never fail the produce that preceded it.
+  }
+}
+
+async function askRatingOnce(): Promise<string | null> {
+  const { createInterface } = await import("node:readline/promises");
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    // 30s and gone: an unattended terminal must not hold the process open —
+    // a timeout is just Enter pressed by nobody.
+    return await rl.question(RATING_PROMPT, { signal: AbortSignal.timeout(30_000) });
+  } catch {
+    return null;
+  } finally {
+    rl.close();
+  }
+}