perso-dubbing 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "perso-dubbing",
       "source": { "source": "npm", "package": "perso-dubbing" },
       "description": "Auto-dub videos into other languages with lip-sync (Perso AI Dubbing), plus voice/background audio separation. Single files, folders, URLs, auto split & merge for long media, multi-language output, resume.",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "author": { "name": "Perso AI" },
       "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
       "repository": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": {
     "name": "Perso Dubbing"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-dubbing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "skills": "./skills/",
   "author": "Perso AI",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
   "displayName": "Perso AI Dubbing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "author": { "name": "Perso AI" },
   "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",

package/README.md

@@ -3,9 +3,11 @@
 [![Powered by Perso AI](https://img.shields.io/badge/Powered%20by-Perso%20AI-5A4FF3)](https://perso.ai)
 ![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)
 ![Agent Skills](https://img.shields.io/badge/Agent%20Skills-SKILL.md-1f6feb)
-![Platforms](https://img.shields.io/badge/platforms-Claude%20Code%20%C2%B7%20Antigravity%20%C2%B7%20Codex%20%C2%B7%20Cursor-555)
+![Platforms](https://img.shields.io/badge/platforms-Claude%20%C2%B7%20Antigravity%20%C2%B7%20Codex%20%C2%B7%20Cursor-555)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
+**English** ｜ [한국어](docs/ko/README.md) ｜ [Español](docs/es/README.md) ｜ [Português](docs/pt/README.md) ｜ [Русский](docs/ru/README.md) ｜ [Bahasa Indonesia](docs/id/README.md) ｜ [Deutsch](docs/de/README.md) ｜ [ไทย](docs/th/README.md) ｜ [日本語](docs/ja/README.md) ｜ [繁體中文](docs/zh-TW/README.md) ｜ [简体中文](docs/zh-CN/README.md) ｜ [Tiếng Việt](docs/vi/README.md) ｜ [Français](docs/fr/README.md)
+
 A coding-agent skill that brings [Perso AI](https://perso.ai)'s **Dubbing (AI dubbing)** to your agent. It **auto-dubs** videos into other languages — a single file or a whole folder, and even oversized or very long media is automatically split, processed, and merged back together. It can also **lip-sync** the dubbed video and **separate voice from background audio**.
 
 It calls the Perso Dubbing API under the hood, so **a Perso Dubbing API key is required.** → <a href="https://developers.perso.ai/api-keys" target="_blank" rel="noopener noreferrer">Get an API key</a>
@@ -14,19 +16,39 @@ Because every host uses the same **Agent Skills standard** (`SKILL.md`), it work
 
 ---
 
-## Quick start (first time)
+## 🖥️ Easiest way — the Claude desktop app (about 3 minutes)
+
+> 📖 **Prefer pictures?** Follow the **[step-by-step visual guide →](https://est-perso-dubbing-agent.github.io/perso-dubbing-plugin/)** (English · 한국어)
+
+No terminal needed. In the <a href="https://claude.ai/download" target="_blank" rel="noopener noreferrer">Claude desktop app</a> (paid plan):
+
+1. **Open the Code tab** (top center) and pick any folder — choose the **Local** environment (plugins are not available in cloud sessions).
+2. **Paste each command** into the prompt box and press Enter, one at a time:
+
+   ```text
+   /plugin marketplace add est-perso-dubbing-agent/perso-dubbing-plugin
+   ```
+
+   ```text
+   /plugin install perso-dubbing@perso-ai
+   ```
 
-1. **Create an empty folder** and open your coding agent (Claude Code · Codex · Cursor · Antigravity) in it.
-2. **Tell the agent to install the plugin** — paste this repository's URL and say *"install this"* (or run `npx perso-dubbing` yourself).
-3. **Ask it to dub a video** — e.g. *"Dub this video into English — C:\videos\clip.mp4"* (a YouTube URL or a whole folder works too). On first run it will open a key file for your Perso API key. Unless you pass `--out`, results are saved next to the source video.
+   *Prefer clicking? After the first command, press the **+** button next to the prompt box → **Plugins** → **Add plugin** → install **perso-dubbing**.*
+3. **Ask for a dub** — e.g. *"Dub this video into English — C:\videos\clip.mp4"* (a YouTube URL or a whole folder works too). On the first run a key file opens for your <a href="https://developers.perso.ai/api-keys" target="_blank" rel="noopener noreferrer">Perso API key</a> — paste the key into that file, **not into the chat**. Unless you pass `--out`, results are saved next to the source video.
+
+> 💡 The skill itself runs on **Node.js 18+**. If your PC doesn't have it, the agent will say `node` was not found — just reply *"install Node.js for me"* (or grab the LTS from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a>), then try again.
+
+The same two `/plugin` commands also work in the **Claude Code CLI**.
 
 ---
 
-## Install
+## Install on other hosts
+
+The shortcut that works everywhere: paste this repository's URL into your agent and say *"install this."*
 
 > **🤖 To the agent:** If you were given only this repository's URL, pick the path for your host:
 >
-> - **Claude Code:** do **not** run npx right away — even if the user said "install this". Show the user the two plugin-marketplace commands below and ask them to type the commands themselves (they are user-typed slash commands you cannot execute). Fall back to npx only if the user still wants you to handle the install after seeing them.
+> - **Claude Code (desktop app or CLI):** do **not** run npx right away — even if the user said "install this". Show the user the two `/plugin` commands from the *Claude desktop app* section above and ask them to type the commands themselves, one per message (they are user-typed slash commands you cannot execute). Also mention the desktop-app click path: after the first command, **+ button → Plugins → Add plugin**. If you need to tailor the wording, `CLAUDE_CODE_ENTRYPOINT=cli` in your shell env suggests a terminal session (undocumented signal — when unsure, present both paths). Fall back to npx only if the user still wants you to handle the install after seeing them.
 > - **Codex · Cursor · Antigravity, or the user delegated the install to you:** run this single command — it fetches the package, auto-detects every installed host, and installs the skill into each:
 >
 > ```bash
@@ -35,14 +57,8 @@ Because every host uses the same **Agent Skills standard** (`SKILL.md`), it work
 >
 > If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed).
 
-### Claude Code (plugin marketplace — recommended)
-
-```text
-/plugin marketplace add est-perso-dubbing-agent/perso-dubbing-plugin
-/plugin install perso-dubbing@perso-ai
-```
-
-### Codex
+<details>
+<summary><b>Codex</b></summary>
 
 Codex reads skills from the shared Agent Skills folder. Run `npx perso-dubbing --codex`, or copy manually:
 
@@ -54,7 +70,10 @@ Codex reads skills from the shared Agent Skills folder. Run `npx perso-dubbing -
 
 The repo also ships a Codex plugin manifest (`.codex-plugin/plugin.json`) for marketplace-based installs.
 
-### Cursor
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
 
 Run `npx perso-dubbing --cursor`, or copy into:
 
@@ -65,7 +84,10 @@ Run `npx perso-dubbing --cursor`, or copy into:
 
 The repo ships a Cursor plugin manifest (`.cursor-plugin/plugin.json`) for the Cursor plugin marketplace.
 
-### Antigravity
+</details>
+
+<details>
+<summary><b>Antigravity</b></summary>
 
 Run `npx perso-dubbing --antigravity`, or copy into either location:
 
@@ -74,7 +96,10 @@ Run `npx perso-dubbing --antigravity`, or copy into either location:
 ~/.agents/skills/dubbing/        # Antigravity 2.0+ (shared Agent Skills folder)
 ```
 
-### ⚡ One-line installer (any host)
+</details>
+
+<details>
+<summary><b>⚡ One-line installer (any host)</b></summary>
 
 Detects which hosts you use and installs to all of them — no clone needed:
 
@@ -87,7 +112,10 @@ npx perso-dubbing
 
 Already have the repo cloned? `node scripts/install.mjs` from the repo root does the same without any network.
 
-### 🔧 Manual install
+</details>
+
+<details>
+<summary><b>🔧 Manual install</b></summary>
 
 Copy the skill folder into your host's skills directory under the name **`dubbing`**. From the repo root:
 
@@ -98,6 +126,8 @@ mkdir -p <skills_folder>/dubbing && cp -r skills/dubbing/* <skills_folder>/dubbi
 
 > 💡 Windows (PowerShell): `New-Item -ItemType Directory -Force <skills_folder>\dubbing; Copy-Item .\skills\dubbing\* <skills_folder>\dubbing\ -Recurse`
 
+</details>
+
 After installing, type **`/dubbing`** in your agent or just say **"dub this video for me"** to run it.
 
 ---
@@ -133,21 +163,32 @@ npm run dub -- "clip.mp4" --separate
 
 ## Troubleshooting
 
+More questions? See the **[FAQ](FAQ.md)**.
+
 | Symptom | Fix |
 |---|---|
-| Install/run fails | Requires **Node.js 18+**. Check with `node -v`. |
+| Claude desktop app asks for Git (Windows) | The Code tab needs <a href="https://git-scm.com/downloads/win" target="_blank" rel="noopener noreferrer">Git for Windows</a> on first use. Install it, then restart the app. |
+| `/plugin` commands or the Plugins menu do nothing | You are in a **cloud session** — plugins only work in **Local** (and SSH) sessions. Switch the environment to Local and retry. |
+| `node` not found / install or run fails | The skill runs on **Node.js 18+** — check with `node -v`. If missing, install the LTS from <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">nodejs.org</a>, or simply ask Claude in the session to install it for you, then restart the app. |
 | No API key yet | Just run any dubbing command — a key file opens automatically; paste your key and save (it's encrypted and the file is deleted). Manual check: `npm run key:check`. **Do not paste the key into the chat.** → <a href="https://developers.perso.ai/api-keys" target="_blank" rel="noopener noreferrer">Get an API key</a> |
 | ffmpeg-related error | ffmpeg is normally installed automatically. If it fails, run `npm run doctor`. |
 | Stops midway (out of credits, crash, killed process) | Progress is saved to a `*.dubresume.json` state file throughout the run. Run the **`--resume "<state-file>"`** command shown in the notice to finish only the remaining parts (completed parts are skipped automatically). |
 
 ---
 
+## Privacy & Telemetry
+
+`/dubbing` sends **anonymous** usage events to improve the skill — for example, which action ran (dub / lip-sync / separate), whether it succeeded, the language pair, app version, and OS. It is tagged only with a random per-install ID and never includes your API key, file names or media content, account/email, or workspace IDs.
+
+---
+
 ## Repository layout
 
 ```text
 .claude-plugin/    Claude Code plugin + marketplace manifests
 .codex-plugin/     Codex plugin manifest
 .cursor-plugin/    Cursor plugin manifest
+docs/              Step-by-step visual install guide (GitHub Pages)
 skills/dubbing/    The skill itself (SKILL.md · lib/ · scripts/) — self-contained
 scripts/           Repo-level installer (install.mjs)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-dubbing",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Perso AI video auto-dubbing agent skill — dubbing, lip-sync, audio separation (Claude Code / Codex / Cursor / Antigravity)",
   "license": "MIT",
   "type": "module",

package/skills/dubbing/SKILL.md

@@ -26,7 +26,7 @@ A skill that auto-dubs videos via the Perso AI Dubbing API.
 
 After the key gate, collect the input (local path or URL — re-ask if missing) and run **in the background**:
 
-- Single: `node scripts/dubbing.mjs "<file|URL>" [--source auto] [--target en] [--space "space name"] [--out result.mp4] [--lipsync]`
+- Single: `node scripts/dubbing.mjs "<file|URL>" [--source auto] [--target en] [--space "space name"] [--out result.mp4] [--lipsync] [--no-save]`
 - Multi-language / multi-input (one or more inputs; URLs and files can be mixed): `node scripts/dubbing.mjs "<URL>" "<file>" --target en,ja` — one output per input × language, saved next to each source (`--out <folder>` collects them).
 - Folder (batch): `node scripts/dubbing.mjs "<folder>" [--target en,zh] [--recursive] [--out output-folder]`
 
@@ -34,6 +34,8 @@ After the key gate, collect the input (local path or URL — re-ask if missing)
 
 **Split confirmation** — if the input exceeds the length or size limit and must be auto split & merged (dubbing, dub+lip-sync, or audio separation), the worker stops (exit 3) and prints `[split-confirm]` lines. Relay them and ask the user: it exceeds the length/size limit, so it needs **automatic split → process → merge**, which can come out **less polished than splitting it up themselves** — proceed automatically? On a yes, re-run the **same command with `--allow-split`** (nothing is billed until this point, so re-running is free). Batch runs: `--allow-split` authorizes every split in the run.
 
+**Don't save (server-only)** — when the user wants the video dubbed but **not** saved as a local file, add `--no-save`: the worker leaves the result in the user's Perso workspace and skips the download, printing `Kept on server, not saved: … → project <seq>` (the `[project-ref]` line is still emitted, so the dub can be lip-synced or retrieved later). **Single/unsplit videos only** — a split video's merged file needs a local download, so it is saved normally and the worker says so. Cannot be combined with `--lipsync` (the lip-synced video must be downloaded).
+
 While it runs (for explaining the wait):
 
 - **Split**: the whole file is uploaded first; only a plan-limit rejection installs ffmpeg and splits losslessly. External URLs (YouTube·TikTok·Drive·Vimeo) are handled server-side.
@@ -131,6 +133,7 @@ The notice lists both commands; pick the one matching how it was installed. It n
 - `PERSO_QUEUE_WAIT_MS` — how long to wait between queue re-checks when all slots are occupied by other jobs (default 5 minutes).
 - `PERSO_LIPSYNC_IDLE_MS` — no-progress allowance for a lip-sync job whose video length is unknown (default 3 hours).
 - `PERSO_NO_UPDATE_CHECK` — skip the once-a-day npm version-update check (headless/CI, or to avoid the extra network call).
+- `PERSO_NO_TELEMETRY` — turn off anonymous usage telemetry (opt-out). No account/key/file data is ever sent; see the README "Privacy & Telemetry" section.
 
 ## Advanced (debug only — not part of the normal flow)
 

package/skills/dubbing/lib/scheduler.mjs

@@ -204,16 +204,22 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
             continue;
           }
           if (opts.lipsync && chunk.kind === 'audio') log(`${tag} is audio — lip-sync skipped, delivering the dubbed audio`);
-          const out = join(outDir, `dub_${chunk.inputId}_${String(chunk.index).padStart(3, '0')}_${chunk.target}.mp4`);
-          try {
-            const dl = await download(pid, spaceSeq, { kind: chunk.kind, outPath: out });
-            setResult(chunk, { status: 'OK', projectId: pid, path: out, name: dl.fileName });
-            log(`${tag} done`);
-          } catch {
-            // generation succeeded (has projectSeq) — only download failed. Don't re-dub; mark it as DLFAIL to
-            // preserve projectSeq → re-download on resume (no regeneration).
-            setResult(chunk, { status: 'DLFAIL', projectId: pid, reason: 'download_failed' });
-            log(`${tag} generated (download failed → re-download on resume)`);
+          if (chunk.noDownload) {
+            // --no-save (server-only): the result stays on the server; record the projectSeq and skip download/merge/save.
+            setResult(chunk, { status: 'OK', projectId: pid, serverOnly: true });
+            log(`${tag} done — kept on server (not downloaded)`);
+          } else {
+            const out = join(outDir, `dub_${chunk.inputId}_${String(chunk.index).padStart(3, '0')}_${chunk.target}.mp4`);
+            try {
+              const dl = await download(pid, spaceSeq, { kind: chunk.kind, outPath: out });
+              setResult(chunk, { status: 'OK', projectId: pid, path: out, name: dl.fileName });
+              log(`${tag} done`);
+            } catch {
+              // generation succeeded (has projectSeq) — only download failed. Don't re-dub; mark it as DLFAIL to
+              // preserve projectSeq → re-download on resume (no regeneration).
+              setResult(chunk, { status: 'DLFAIL', projectId: pid, reason: 'download_failed' });
+              log(`${tag} generated (download failed → re-download on resume)`);
+            }
           }
         } else if (st.noVoice) {
           // no voice detected. For a split chunk (has endMs), pass the original through → keep silent segments of a long video and dub·merge the rest.

package/skills/dubbing/lib/telemetry.mjs

@@ -0,0 +1,75 @@
+// Anonymous, opt-out usage telemetry → Amplitude HTTP API (/2/httpapi). Non-blocking and
+// fail-silent: never delays or fails a run. No personal data — a random per-install UUID
+// (~/.perso/install-id), coarse environment, and the caller-supplied counts only. No API key,
+// filenames, media content, account/email, or spaceSeq/projectSeq is ever sent.
+// Opt out with PERSO_NO_TELEMETRY. See README "Telemetry & Privacy".
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { CRED_DIR } from './config.mjs';
+import { CLIENT_VERSION, CLIENT_HOST } from './client_info.mjs';
+
+// Write-only ingestion (project API) key. Public by design — it can only SEND events, never read
+// data; exposure in the repo allows spoofing at worst, not data access. Override via env for testing.
+const API_KEY = process.env.PERSO_AMPLITUDE_KEY || 'd795c0c0328160be4d7df3365eb0c05e';
+// US data residency. EU projects must use https://api.eu.amplitude.com/2/httpapi.
+const ENDPOINT = process.env.PERSO_AMPLITUDE_URL || 'https://api2.amplitude.com/2/httpapi';
+const TIMEOUT_MS = 3000;
+
+const ID_FILE = join(CRED_DIR, 'install-id');
+const NODE_MAJOR = Number(process.versions.node.split('.')[0]) || null;
+
+// Stable per install (machine × OS user): a random UUID persisted to ~/.perso/install-id and read
+// on every run → same value across sessions and reboots. Returns { id, isNew }; isNew is true only
+// the first time the file is created (→ emit `first_run` once). A write failure (read-only FS, CI)
+// yields a fresh id each run — accepted; it only over-counts in ephemeral environments.
+function loadInstallId() {
+  try {
+    const id = readFileSync(ID_FILE, 'utf8').trim();
+    if (id) return { id, isNew: false };
+  } catch { /* create below */ }
+  const id = randomUUID();
+  try { mkdirSync(CRED_DIR, { recursive: true }); writeFileSync(ID_FILE, id); } catch { /* best-effort */ }
+  return { id, isNew: true };
+}
+
+let cached = null;
+const installId = () => (cached ??= loadInstallId());
+
+/** Fire one event. Fail-silent and never throws; safe to call without awaiting (the run drains the
+ *  pending request on exit). null/undefined properties are dropped so only set fields are sent. */
+export async function track(eventType, props = {}) {
+  if (process.env.PERSO_NO_TELEMETRY || !API_KEY) return;
+  try {
+    const event_properties = NODE_MAJOR ? { node_major: NODE_MAJOR } : {};
+    for (const [k, v] of Object.entries(props)) if (v != null) event_properties[k] = v;
+    const res = await fetch(ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+      body: JSON.stringify({
+        api_key: API_KEY,
+        events: [{
+          device_id: installId().id,
+          event_type: eventType,
+          time: Date.now(),
+          app_version: CLIENT_VERSION,
+          platform: CLIENT_HOST, // 'agents' — one unified channel
+          os_name: process.platform, // win32 | darwin | linux
+          event_properties,
+        }],
+      }),
+    });
+    if (process.env.PERSO_TELEMETRY_DEBUG) console.error(`[telemetry] ${eventType} → HTTP ${res.status} ${JSON.stringify(event_properties)}`);
+  } catch (e) {
+    if (process.env.PERSO_TELEMETRY_DEBUG) console.error(`[telemetry] ${eventType} → failed: ${e?.message ?? e}`);
+    /* non-blocking, fail-silent */
+  }
+}
+
+/** Call once at process start (before other track calls). Emits `first_run` the first time this
+ *  install is seen. No-op when opted out. Safe to call unconditionally; never throws. */
+export function initTelemetry() {
+  if (process.env.PERSO_NO_TELEMETRY) return;
+  try { if (installId().isNew) track('first_run'); } catch { /* fail-silent */ }
+}

package/skills/dubbing/scripts/billing.mjs

@@ -12,6 +12,7 @@ import {
   withCurrencyFallback, isCurrencyMismatch, CREDIT_PER_UNIT, DEFAULT_CURRENCY, CURRENCIES,
 } from '../lib/billing.mjs';
 import { withUtm, SUBSCRIPTION_URL } from '../lib/messages.mjs';
+import { track } from '../lib/telemetry.mjs';
 
 class UsageError extends Error { constructor(m) { super(m); this.name = 'UsageError'; } }
 class ExitCode extends Error { constructor(c) { super(`exit ${c}`); this.name = 'ExitCode'; this.code = c; } }
@@ -130,6 +131,7 @@ async function runOptions(args) {
 // ---- link: generate the Stripe URL for the confirmed choice ----
 async function runLink(args) {
   const spaceSeq = await resolveSpaceSeq(args.space);
+  const fromTier = (await getPlanStatus(spaceSeq).catch(() => null))?.planTier ?? null; // for billing_link_created telemetry
   const modes = [args.checkout && 'checkout', args.billing && 'billing', args.credits && 'credits'].filter(Boolean);
   if (modes.length !== 1) throw new UsageError('Pass exactly one of --checkout, --billing, --credits.');
   const mode = modes[0];
@@ -141,7 +143,7 @@ async function runLink(args) {
     const plans = await getRecurringPlans(spaceSeq, { billingPeriod: args.period, currency });
     const sel = findPriceOption(plans, args.plan, args.period);
     if (!sel?.opt?.priceId) throw new UsageError(`No ${args.plan} plan for ${args.period}/${currency} (starter has no yearly). Check the tier and period.`);
-    return printLink(await createCheckoutLink({ spaceSeq, priceId: sel.opt.priceId, planSeq: sel.planSeq }), `${args.plan} ${args.period} (${currency.toUpperCase()})`);
+    return printLink(await createCheckoutLink({ spaceSeq, priceId: sel.opt.priceId, planSeq: sel.planSeq }), `${args.plan} ${args.period} (${currency.toUpperCase()})`, { link_type: 'checkout', from_tier: fromTier, upgrade_plan: args.plan });
   }
 
   if (mode === 'billing') {
@@ -171,7 +173,7 @@ async function runLink(args) {
       console.log(`Ask the user to change their plan in the Perso portal: ${withUtm(SUBSCRIPTION_URL)}`);
       return;
     }
-    return printLink(link, `change to ${args.plan} (${currency.toUpperCase()})`);
+    return printLink(link, `change to ${args.plan} (${currency.toUpperCase()})`, { link_type: 'billing', from_tier: fromTier, upgrade_plan: args.plan, currency_fallback: currency !== preferred });
   }
 
   // credits
@@ -179,11 +181,12 @@ async function runLink(args) {
   if (!Number.isInteger(quantity) || quantity < 1) throw new UsageError('--credits needs --quantity <positive integer>.');
   const prod = await getCreditProduct(spaceSeq);
   if (!prod?.priceId) throw new Error('Credit product unavailable for this space.');
-  printLink(await createOneTimeLink({ spaceSeq, priceId: prod.priceId, planSeq: prod.planSeq, quantity }), `${quantity} credit pack(s) = ${quantity * CREDIT_PER_UNIT} credits`);
+  printLink(await createOneTimeLink({ spaceSeq, priceId: prod.priceId, planSeq: prod.planSeq, quantity }), `${quantity} credit pack(s) = ${quantity * CREDIT_PER_UNIT} credits`, { link_type: 'onetime', from_tier: fromTier, credit_amount: quantity * CREDIT_PER_UNIT });
 }
 
-function printLink(link, what) {
+function printLink(link, what, meta = {}) {
   if (!link) throw new Error('The payment service did not return a link. Please try again.');
+  track('billing_link_created', meta);
   console.log(`Payment link (${what}):`);
   console.log(`  ${link}`);
   console.log(HANDOFF);

package/skills/dubbing/scripts/dubbing.mjs

@@ -19,6 +19,7 @@ import { download, getStatus, upload, requestAudioSeparation, downloadSeparation
 import { mergeGroups } from '../lib/merge.mjs';
 import { messages, withUtm, SUBSCRIPTION_URL } from '../lib/messages.mjs';
 import { checkForUpdate } from '../lib/update_check.mjs';
+import { track, initTelemetry } from '../lib/telemetry.mjs';
 import { cleanupTempDirs, makeTempDir } from '../lib/tmp.mjs';
 import { probe } from '../lib/ffmpeg.mjs';
 import { AUDIO_EXT, CREDIT_RATE_DUB, CREDIT_RATE_LIPSYNC, UHD_CREDIT_MULT, UHD_BILLED_TIERS, POLL_INTERVAL_MS, MAX_IDLE_MS } from '../lib/config.mjs';
@@ -39,17 +40,51 @@ function friendlyError(e) {
   return e?.message ?? 'Unknown error';
 }
 
+// Coarse error bucket for telemetry — never the raw message/code.
+function errorClass(e) {
+  if (e?.name === 'MissingKeyError' || isAuthError(e)) return 'auth';
+  if (e?.name === 'UnsupportedMediaError') return 'unsupported';
+  if (e?.name === 'PersoApiError') return 'network';
+  return 'unknown';
+}
+
+// split-confirm telemetry props: real units + an ESTIMATED part count (the exact split isn't computed until the confirmed re-run).
+function splitConfirmProps(d = {}) {
+  const SIZE_CAP = 1.9 * 1024 ** 3; // mirrors split.mjs SIZE_CAP (estimate only)
+  if (d.reason === 'length') {
+    return {
+      reason: 'length',
+      duration_sec: Number.isFinite(d.actualMs) ? Math.round(d.actualMs / 1000) : null,
+      parts_est: (Number.isFinite(d.actualMs) && d.limitMs) ? Math.ceil(d.actualMs / d.limitMs) : null,
+    };
+  }
+  return {
+    reason: 'size',
+    size_mb: Number.isFinite(d.actualBytes) ? Math.round(d.actualBytes / 1024 ** 2) : null,
+    parts_est: Number.isFinite(d.actualBytes) ? Math.ceil(d.actualBytes / SIZE_CAP) : null,
+  };
+}
+
+// Sum of known chunk spans across inputs → seconds (null when no boundaries are known, e.g. an unsplit whole).
+function totalDurationSec(perInput) {
+  const ms = (perInput || []).reduce((s, p) => s + (p.chunks || []).reduce(
+    (a, c) => a + (Number.isFinite(c.startMs) && Number.isFinite(c.endMs) ? c.endMs - c.startMs : 0), 0), 0);
+  return ms > 0 ? Math.round(ms / 1000) : null;
+}
+
 // Key gate with self-healing: when no key is registered, hand off to `resolve_key.mjs --watch` in a child
 // process (creates the key file, opens it in the editor, encrypts on save, deletes the file) and continue
 // once registered. Runs in a child because Windows DPAPI work (powershell) must not run in this main process.
 // PERSO_NO_WATCH=1 restores the old fail-fast behavior (headless/CI).
 async function ensureKey() {
-  if (resolveKey()) return;
+  if (resolveKey()) { track('key_check', { has_key: true }); return; }
+  track('key_check', { has_key: false });
   if (process.env.PERSO_NO_WATCH) {
     console.error(onboardingHelp());
     throw new ExitCode(2);
   }
   notify('No API key registered — a key file will open; paste just your Perso API key and save it. (Get one: https://developers.perso.ai/api-keys)');
+  track('key_onboarding_started');
   const watcher = fileURLToPath(new URL('./resolve_key.mjs', import.meta.url));
   const code = await new Promise((res) => {
     const child = spawn(process.execPath, [watcher, '--watch'], { stdio: 'inherit' });
@@ -61,6 +96,7 @@ async function ensureKey() {
     console.error(onboardingHelp());
     throw new ExitCode(2);
   }
+  track('key_registered');
   notify('API key registered — continuing.');
 }
 
@@ -71,9 +107,9 @@ async function ensureKey() {
 // --space "<space name>".
 async function ensureSpace(args) {
   const wanted = args.space != null ? String(args.space).trim() : '';
-  if (/^\d+$/.test(wanted)) return Number(wanted); // raw seq — power users/scripts; not shown to end users
+  if (/^\d+$/.test(wanted)) { track('space_resolved'); return Number(wanted); } // raw seq — power users/scripts; not shown to end users
   const pinned = Number(process.env.PERSO_SPACE_SEQ);
-  if (!wanted && pinned) return pinned;
+  if (!wanted && pinned) { track('space_resolved'); return pinned; }
 
   const spaces = await dubbingSpaces();
   // Options shown to the user carry "name | (plan) | remaining credits" — never the internal seq.
@@ -84,7 +120,7 @@ async function ensureSpace(args) {
 
   if (wanted) {
     const hits = spaces.filter((s) => s.name.toLowerCase() === wanted.toLowerCase());
-    if (hits.length === 1) { console.log(`Space: ${brief(hits[0])}`); return hits[0].seq; }
+    if (hits.length === 1) { track('space_resolved', { plan_tier: hits[0].tier ?? null }); console.log(`Space: ${brief(hits[0])}`); return hits[0].seq; }
     if (hits.length > 1) {
       console.log(`[space-select] Several spaces share the name "${wanted}" — rename one in Perso, or pin PERSO_SPACE_SEQ:`);
       for (const s of await enrich(hits)) console.log(`  PERSO_SPACE_SEQ=${s.seq}  →  ${label(s)}`);
@@ -95,7 +131,7 @@ async function ensureSpace(args) {
     throw new ExitCode(3);
   }
 
-  if (spaces.length === 1) return spaces[0].seq;
+  if (spaces.length === 1) { track('space_resolved', { plan_tier: spaces[0].tier ?? null }); return spaces[0].seq; }
   const options = await enrich(spaces);
   if (process.stdin.isTTY && process.stdout.isTTY) {
     console.log('Several spaces are available. Which one should this dubbing run in?');
@@ -105,6 +141,7 @@ async function ensureSpace(args) {
     rl.close();
     const chosen = options[Number(answer) - 1] ?? options.find((s) => s.name.toLowerCase() === answer.toLowerCase());
     if (!chosen) { console.error('Invalid selection — run again.'); throw new ExitCode(1); }
+    track('space_resolved', { plan_tier: chosen.tier ?? null });
     console.log(`Space: ${brief(chosen)}`);
     return chosen.seq;
   }
@@ -114,7 +151,7 @@ async function ensureSpace(args) {
 }
 
 const USAGE = [
-  'Usage: node scripts/dubbing.mjs "<file|folder|URL>" ["<another input>" ...] [--source auto] [--target en,ja] [--space "space name"] [--out path|folder] [--recursive] [--lipsync] [--force]',
+  'Usage: node scripts/dubbing.mjs "<file|folder|URL>" ["<another input>" ...] [--source auto] [--target en,ja] [--space "space name"] [--out path|folder] [--recursive] [--lipsync] [--force] [--no-save]',
   '       node scripts/dubbing.mjs --lipsync-only "<project-ref JSON | projectSeq[,projectSeq...]>" [--space "space name"] [--out path|folder]',
   '       node scripts/dubbing.mjs --separate "<file|folder|URL>" ["<another input>" ...] [--space "space name"] [--out folder]',
   '       node scripts/dubbing.mjs --resume "<state-file>"',
@@ -123,6 +160,7 @@ const USAGE = [
   '  --lipsync-only  lip-sync an already-dubbed project (uses the [project-ref] line printed by a finished run; no re-dub charge)',
   '  --separate      split the source into voice / background / sub-background audio tracks (no dubbing; ~0.5 credit per second)',
   '  --force         skip the upfront credit-estimate gate of --lipsync',
+  '  --no-save       leave the result on the server without downloading it (single/unsplit input only; not with --lipsync)',
 ].join('\n');
 
 class UsageError extends Error {
@@ -147,6 +185,7 @@ function parseArgs(argv) {
     else if (t === '--lipsync') a.lipsync = true;
     else if (t === '--force') a.force = true;
     else if (t === '--allow-split') a.allowSplit = true; // user confirmed auto split→dub→merge (set on the re-run after [split-confirm])
+    else if (t === '--no-save') a.noSave = true; // server-only: skip downloading the result (single/unsplit input only)
     else if (t in VALUE_FLAGS) {
       const v = argv[++i];
       if (v === undefined || v.startsWith('--')) throw new UsageError(`Missing value for ${t}`);
@@ -168,6 +207,7 @@ async function validateLanguages(targets, source) {
   const fixed = targets.map((t) => {
     const hit = canon.get(t.toLowerCase());
     if (!hit) {
+      track('lang_invalid', { field: 'target' });
       console.error(`Unsupported target language code: "${t}"\nSupported: ${codes.join(', ')}`);
       throw new ExitCode(1);
     }
@@ -177,6 +217,7 @@ async function validateLanguages(targets, source) {
   if (source && source !== 'auto') {
     const hit = canon.get(source.toLowerCase());
     if (!hit) {
+      track('lang_invalid', { field: 'source' });
       console.error(`Unsupported source language code: "${source}" (use "auto" to detect)\nSupported: ${codes.join(', ')}`);
       throw new ExitCode(1);
     }
@@ -324,7 +365,7 @@ function buildManifest(ctx, perInput, results, prevDone = {}) {
   }
   return {
     version: 5, spaceSeq: ctx.spaceSeq, opts: { source: ctx.source }, targets: ctx.targets, out: ctx.out ?? null,
-    lipsync: !!ctx.lipsync,
+    lipsync: !!ctx.lipsync, stop_reason: ctx.stopReason ?? null,
     inputs: perInput.map((p) => ({
       inputId: p.inputId, ref: p.ref,
       chunks: p.chunks.map((c) => ({
@@ -420,6 +461,13 @@ async function finishPool(allResults, perInput, ctx) {
         failCount++;
         continue;
       }
+      if (mergeable.length && mergeable.every((r) => r.serverOnly)) {
+        // --no-save: the dubbed result was left on the server and never downloaded → report + reference, don't merge/save.
+        lines.push(`Kept on server, not saved: ${tlab} → project ${mergeable[0].projectId}`);
+        okCount++;
+        emitProjectRef(pin, tRes, target, ctx, { lipsync: false });
+        continue;
+      }
       const hasLs = mergeable.some((r) => r.lipsync);
       const lsFailed = mergeable.some((r) => r.lipsyncFailed);
       const lsPending = mergeable.some((r) => r.lipsyncPending);
@@ -454,12 +502,14 @@ async function finishPool(allResults, perInput, ctx) {
   const dlPending = allResults.some((r) => r.status === 'DLFAIL');
   const stopped = !!ctx.sched?.stopped;
   if (stopped || dlPending) {
+    ctx.stopReason = stopped ? 'quota' : 'download'; // recorded in the manifest → resume reports why it stopped
     if (ctx.multiInput && ctx.out) mkdirSync(ctx.out, { recursive: true });
     writeFileSync(ctx.file, JSON.stringify(buildManifest(ctx, perInput, allResults, ctx.prevDone ?? {})), 'utf8');
     if (stopped) {
       const plan = await getPlanStatus(ctx.spaceSeq);
       const min = remainingMinutes(ctx.sched.pendingLeft);
       const lsOwed = allResults.some((r) => r.lipsyncPending);
+      track('quota_exceeded', { plan_tier: plan?.planTier ?? null, remaining_min: min });
       console.log('\n' + messages.quotaExceeded({
         planTier: plan?.planTier,
         remainingQuota: plan?.remainingQuota,
@@ -473,10 +523,21 @@ async function finishPool(allResults, perInput, ctx) {
   } else {
     try { unlinkSync(ctx.file); } catch { /* done → clean up resume state-file (ignore if absent) */ }
   }
+  if (!ctx.lipsyncOnly) { // lipsync-only runs report via lipsync_only_started, not dubbing_completed
+    track('dubbing_completed', {
+      input_count: perInput.length, ok_count: okCount, fail_count: failCount,
+      had_split: perInput.some((p) => (p.chunks?.length ?? 0) > 1),
+      had_lipsync: allResults.some((r) => r.lipsync),
+      duration_sec: totalDurationSec(perInput),
+      source_lang: ctx.source, target_lang: (ctx.targets || []).join(','),
+      is_resume: !!ctx.isResume, recovered: !!ctx.isResume && ctx.resumedFrom === 'quota' && okCount > 0,
+    });
+  }
 }
 
 // New run: schedule all inputs as a single pool. Per-input split/upload happens once (secures mediaSeq) → reused per language.
 async function runPool(args) {
+  if (args.noSave && args.lipsync) throw new UsageError('--no-save cannot be combined with --lipsync (the lip-synced video must be downloaded).');
   await ensureKey();
   const wantedTargets = String(args.target).split(',').map((t) => t.trim()).filter(Boolean); // --target en,ja,ko
   if (!wantedTargets.length) throw new UsageError('No target language specified (--target en,ja,...)');
@@ -509,17 +570,20 @@ async function runPool(args) {
       ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
     } catch (e) {
       if (e?.name === 'SplitConfirmNeeded') {
+        track('split_confirm_needed', splitConfirmProps(e.details));
         console.log(splitConfirmMessage(e.details, tag));
         // Nothing is billed yet at the split stage, so discard any partial state so the --allow-split re-run isn't blocked by the resume guard.
         try { if (existsSync(file)) unlinkSync(file); } catch { /* ignore */ }
         throw new ExitCode(3);
       }
-      if (isAuthError(e)) { console.log(`\n${friendlyError(e)}`); return; } // key issues abort everything
+      if (isAuthError(e)) { track('error', { error_class: 'auth' }); console.log(`\n${friendlyError(e)}`); return; } // key issues abort everything
       if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; } // unsupported → skip
       console.log(`${tag} — split/upload failed: ${friendlyError(e)}`); continue;
     }
     if (chunks.length > 1) notify(`Split complete — ${labelOf(inp)} (${chunks.length} parts)`);
-    for (const c of chunks) pool.push({ ...c, inputId: id });
+    const noDownload = !!args.noSave && chunks.length === 1; // --no-save is single-input only; a split video's merged file needs a local download
+    if (args.noSave && chunks.length > 1) notify(`--no-save is not available for split videos (merging needs a local download) — ${labelOf(inp)} will be saved normally.`);
+    for (const c of chunks) pool.push({ ...c, inputId: id, noDownload });
     perInput.push({ inputId: id, inp, ref: refOf(inp), chunks });
     saver.writeNow(); // the chunk plan (boundaries) survives a crash from this point on
   }
@@ -527,6 +591,7 @@ async function runPool(args) {
 
   if (args.lipsync && !args.force) await creditPreflight(perInput, spaceSeq, targets.length);
 
+  track('dub_submitted', { input_count: perInput.length, parts: pool.length, target_count: targets.length, has_lipsync: !!args.lipsync });
   notify(`Translating${targets.length > 1 ? ` (${targets.join(', ')})` : ''}`);
   // Fill all inputs×parts×languages into one queue for concurrent processing. Submit as many as there are empty slots and add more every 5 minutes.
   const sched = await runSchedule(pool, spaceSeq, { source, targets, lipsync: !!args.lipsync }, { log, notify, onResult: saver.onResult, onSubmit: saver.onSubmit });
@@ -565,6 +630,7 @@ async function creditPreflight(perInput, spaceSeq, targetCount) {
     needed += Math.ceil(inputMs / 1000) * (CREDIT_RATE_DUB + CREDIT_RATE_LIPSYNC) * targetCount * mult;
   }
   if (!needed || remaining >= needed) return;
+  track('credit_check_blocked', { credits_needed: needed, credits_remaining: remaining, plan_tier: plan?.planTier ?? null });
   console.log(`[credit-check] Estimated credits for dubbing + lip-sync: ~${needed}${anyUhd ? ` (includes the ×${UHD_CREDIT_MULT} 4K surcharge)` : ''}. Credits left: ${remaining}.`);
   console.log('[credit-check] The run would stop part-way. Ask the user to top up first, or approve continuing anyway — then re-run the same command with --force (whatever completes is kept; the rest resumes later):');
   console.log(`  → ${withUtm(SUBSCRIPTION_URL)}`);
@@ -581,7 +647,8 @@ async function runResume(file) {
   const targets = m.targets ?? [m.opts?.target ?? 'en'];
   const multiInput = (m.inputs?.length ?? 0) > 1;
   const lipsync = !!m.lipsync;
-  const ctx = { spaceSeq: m.spaceSeq, source: m.opts?.source ?? 'auto', targets, out: m.out, multiInput, file, prevDone: m.done ?? {}, lipsync };
+  const ctx = { spaceSeq: m.spaceSeq, source: m.opts?.source ?? 'auto', targets, out: m.out, multiInput, file, prevDone: m.done ?? {}, lipsync, isResume: true, resumedFrom: m.stop_reason ?? 'manual' };
+  track('resume_started', { mode: 'resume', resumed_from: m.stop_reason ?? 'manual' });
   const outDir = await makeTempDir('dubbing-resume-');
   const matCache = new Map(); // `${inputId}|${index}` → re-cut path (once per part, shared across languages)
 
@@ -744,6 +811,8 @@ async function runLipsyncOnly(args) {
   }
   const parts = Array.isArray(ref.parts) ? ref.parts : [];
   if (!parts.some((p) => p?.seq != null)) throw new UsageError('No dubbed project found in the --lipsync-only reference.');
+  const lsMs = parts.reduce((s, p) => { const r = p?.ms ?? p?.pt; return s + (Array.isArray(r) && r.length === 2 ? Math.max(0, r[1] - r[0]) : 0); }, 0);
+  track('lipsync_only_started', { input_count: 1, parts: parts.length, duration_sec: lsMs > 0 ? Math.round(lsMs / 1000) : null });
 
   const target = ref.lang ?? 'out';
   const localPath = ref.input && !/^[a-z]+:\/\//i.test(ref.input) ? ref.input : null;
@@ -751,7 +820,7 @@ async function runLipsyncOnly(args) {
   const file = resumePath({ out: args.out, inputs: [inp], multiInput: false });
   guardExistingState(file); // an interrupted earlier run owns this state file — resume it instead of re-billing
   const spaceSeq = Number(ref.space) || await ensureSpace(args);
-  const ctx = { spaceSeq, source: 'auto', targets: [target], out: args.out, multiInput: false, file, prevDone: {}, lipsync: true };
+  const ctx = { spaceSeq, source: 'auto', targets: [target], out: args.out, multiInput: false, file, prevDone: {}, lipsync: true, lipsyncOnly: true };
 
   const chunks = parts.map((p, i) => ({
     index: i, source: 'local',
@@ -839,6 +908,7 @@ async function runSeparation(args) {
       ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
     } catch (e) {
       if (e?.name === 'SplitConfirmNeeded') {
+        track('split_confirm_needed', splitConfirmProps(e.details));
         console.log(splitConfirmMessage(e.details, multiInput ? labelOf(inp) : null, 'separate'));
         try { if (existsSync(file)) unlinkSync(file); } catch { /* nothing billed yet → safe to discard */ }
         throw new ExitCode(3);
@@ -853,7 +923,7 @@ async function runSeparation(args) {
   if (!perInput.length) { notify('No inputs to separate.'); return; }
   notify('Separating voice/background');
   // Phase 2 — submit (checkpointed) → wait → download → merge → save.
-  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, null);
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, null, false);
   finishSepState(file, pending);
 }
 
@@ -886,13 +956,13 @@ async function runResumeSeparation(m, file) {
     if (!recutCache.has(mk)) recutCache.set(mk, await recutChunk(pin._localPath, c.startMs, c.endMs));
     return recutCache.get(mk);
   };
-  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, materializeFor);
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, materializeFor, true);
   finishSepState(file, pending);
 }
 
 // Per-input: separate every chunk (checkpointing each submission), merge tracks, save. Shared by run + resume.
 // Returns true when some paid part is still owed (undelivered) → the caller must keep the state file for resume.
-async function separationProcess(perInput, spaceSeq, ctx, saver, materializeFor) {
+async function separationProcess(perInput, spaceSeq, ctx, saver, materializeFor, isResume = false) {
   const usedByDir = new Map();
   const lines = [];
   let ok = 0, fail = 0;
@@ -919,6 +989,7 @@ async function separationProcess(perInput, spaceSeq, ctx, saver, materializeFor)
   }
   console.log('\n' + lines.join('\n'));
   if (perInput.length > 1) console.log(`\nSummary: ${ok} done · ${fail} failed`);
+  track('separation_completed', { input_count: perInput.length, ok_count: ok, fail_count: fail, duration_sec: totalDurationSec(perInput), is_resume: isResume });
   return flags.pending;
 }
 
@@ -1018,7 +1089,17 @@ async function main() {
   try {
     preloadKeyEnv(); // pre-inject the key into env before async (at a clean point) → avoid a synchronous powershell call/crash in the main process
     const args = parseArgs(process.argv.slice(2));
-    if (!args.help) updateNotice = checkForUpdate().catch(() => null); // non-blocking; never fails the run
+    if (!args.help) {
+      updateNotice = checkForUpdate().catch(() => null); // non-blocking; never fails the run
+      initTelemetry(); // emits first_run once per install
+      track('run_started', {
+        mode: args.resume ? 'resume' : args.separate ? 'separate' : args.lipsyncOnly ? 'lipsync-only' : args.lipsync ? 'lipsync' : 'dub',
+        input_count: args.inputs.length || null,
+        target_count: String(args.target).split(',').map((s) => s.trim()).filter(Boolean).length || null,
+        has_lipsync: !!(args.lipsync || args.lipsyncOnly),
+        source_lang: args.source,
+      });
+    }
     if (args.help) console.log(USAGE);
     else if (args.resume) await runResume(args.resume);
     else if (args.separate) {
@@ -1036,7 +1117,7 @@ async function main() {
   } catch (e) {
     if (e?.name === 'ExitCode') exitCode = e.code; // message already printed at the throw site
     else if (e?.name === 'UsageError') { console.error(`${e.message}\n${USAGE}`); exitCode = 1; }
-    else { console.error(friendlyError(e)); exitCode = 1; }
+    else { track('error', { error_class: errorClass(e) }); console.error(friendlyError(e)); exitCode = 1; }
   } finally {
     await cleanupTempDirs(); // bulk-clean the cut/schedule/merge/download temp folders
   }