perso-dubbing 0.3.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.3.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.3.0",
+  "version": "0.5.0",
   "author": {
     "name": "Perso Dubbing"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-dubbing",
-  "version": "0.3.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.3.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,32 +16,49 @@ 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, run this single command — it fetches the package, auto-detects every installed host (Claude Code · Codex · Cursor · Antigravity), and installs the skill into each:
+> **🤖 To the agent:** If you were given only this repository's URL, pick the path for your host:
+>
+> - **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
 > npx perso-dubbing
 > ```
 >
-> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed). In Claude Code, prefer the plugin-marketplace commands below.
-
-### Claude Code (plugin marketplace — recommended)
-
-```text
-/plugin marketplace add est-perso-dubbing-agent/perso-dubbing-plugin
-/plugin install perso-dubbing@perso-ai
-```
+> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed).
 
-### Codex
+<details>
+<summary><b>Codex</b></summary>
 
 Codex reads skills from the shared Agent Skills folder. Run `npx perso-dubbing --codex`, or copy manually:
 
@@ -51,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:
 
@@ -62,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:
 
@@ -71,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:
 
@@ -84,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:
 
@@ -95,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.
 
 ---
@@ -130,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.3.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,12 +26,16 @@ 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]`
 
 **Space selection** — with several workspaces the worker stops before uploading, prints `[space-select]` lines (**name | (plan) | remaining credits**) and exits (code 3). Show the user ONLY those options (no internal numbers), ask which one, and re-run with `--space "<space name>"`. One space → no question; `PERSO_SPACE_SEQ` pins it.
 
+**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.
@@ -66,7 +70,7 @@ To split voice from background sound (no dubbing involved), run **in the backgro
 - Outputs per input, next to the source (`--out` is a folder here): `<name>.voice.wav` · `<name>.background.wav` · `<name>.sub_background.wav`.
 - Credits ≈ seconds ×0.5. No language options; cannot combine with lip-sync flags.
 - Auto-split/merge, key gate, `[space-select]` and `[progress]` rules apply unchanged.
-- **No resume for separation yet** — re-running an interrupted run re-bills (parts run one at a time, so at most one part is at risk). Don't kill a running separation casually.
+- **Resume** — separation saves the same `*.dubresume.json` state with a per-part checkpoint, so an interrupted run (credits, crash, killed shell) continues with `node scripts/dubbing.mjs --resume "<state-file>"` **without re-submitting already-paid parts**. Re-running the original command is blocked (`[resume-check]`, exit 3) — run the printed `--resume` instead.
 
 ## Interruption & resume
 
@@ -80,12 +84,43 @@ Completed parts are skipped automatically; the state file is deleted when everyt
 
 **Re-running the original command while a state file exists is blocked** — the worker prints `[resume-check]` lines (exit 3) instead of re-billing. Relay the printed `--resume` command and run that. Delete the state file **only** if the user explicitly chooses to pay for the completed parts again — never on your own.
 
-**On an insufficient-credits stop**: deliver the completed parts and relay the worker's upgrade/Get-credits URL and resume command **verbatim** — that URL is plain stdout (not `[progress]`), so don't drop it while summarizing.
+**On an insufficient-credits stop**: deliver the completed parts, then relay the worker's guidance and resume command **verbatim** — plain stdout (not `[progress]`), so don't drop it while summarizing. The guidance points to `scripts/billing.mjs` for a payment link — see **Plan upgrade & credits** below.
+
+## Plan upgrade & credits
+
+When the user runs out of credits (the stop above) **or** asks to upgrade / buy more credits, you can generate a Stripe payment link. **You only ever hand the link to the user — never open it or complete payment yourself**, even if the user asks you to pay.
+
+Run this first — it detects the plan and prints the fitting flow, the choices, and (with `--shortfall`) a recommendation:
+
+`node scripts/billing.mjs options [--shortfall <estimated remaining credits>] [--space "<space name>"]`
+
+It routes by the current plan tier — ask only the question for that branch, then generate the link:
+
+- **free → subscribe.** Ask which plan and **monthly or yearly** (starter is monthly-only). Currency defaults to USD; use KRW only if the user asks.
+  `node scripts/billing.mjs link --checkout --plan <starter|creator|pro> --period <monthly|yearly> [--currency usd|krw]`
+- **starter / creator → change plan.** Ask which plan; billing period and currency are locked to the existing subscription (handled automatically).
+  `node scripts/billing.mjs link --billing --plan <creator|pro>`
+- **pro / business → buy credits.** Ask how many packs (1 pack = 60 credits, USD). With `--shortfall`, `options` recommends a quantity.
+  `node scripts/billing.mjs link --credits --quantity <n>`
+- **enterprise → no self-serve.** Tell the user to contact their workspace administrator.
+
+**Recommending on a credit-out stop**: estimate the remaining work's credits (dubbing ≈ ×1/s · lip-sync ≈ ×2 · separation ≈ ×0.5, and ×3 for 4K on pro+), pass it as `--shortfall`, and relay the tool's recommendation. If even the top self-serve plan or a reasonable credit quantity can't cover it, point the user to their administrator (Enterprise) instead.
+
+Hand the returned link to the user to complete payment in their browser; after they top up, resume the interrupted job with the printed `--resume` command (no re-billing).
 
 ## Perso portal (answer only when asked)
 
 Every run is also a project in the user's Perso portal account. If the user wants more than the delivered files (subtitles, audio-only, other formats) or to browse/re-download earlier projects, point them to https://portal.perso.ai — projects live in the workspace used for the run; split parts are numbered `_01`, `_02`, …. Never add this to progress relays or final reports.
 
+## Version updates
+
+Once a day (first run after 00:00 UTC) the worker checks npm for a newer release and, **after the current job finishes** (never mid-run), may print a one-line `ℹ️  Update available: …` notice. When you see it, relay it and act by install method:
+
+- **Claude Code plugin (marketplace):** tell the user to run `/plugin update perso-dubbing` — a slash command you cannot run yourself.
+- **npx / manual install:** ask the user whether to update, and on yes run `npx perso-dubbing@latest`.
+
+The notice lists both commands; pick the one matching how it was installed. It never blocks a run and can be silenced with `PERSO_NO_UPDATE_CHECK=1`.
+
 ## Config (env)
 
 - `PERSO_API_BASE` — API base URL (default `https://api.perso.ai`). **https `perso.ai` hosts only** — anything else is rejected at startup (the API key travels in a header to this host).
@@ -97,6 +132,8 @@ Every run is also a project in the user's Perso portal account. If the user want
 - `PERSO_SIZE_CAP_BYTES` — upload size cap used for the split decision (default ≈1.9 GB, under the API's 2 GB limit).
 - `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/billing.mjs

@@ -0,0 +1,159 @@
+// Plan-upgrade / credit-purchase helpers. All calls go to the Perso payment service with the same
+// XP-API-KEY the rest of the skill uses; the agent only ever receives a Stripe link to hand to the user —
+// it must never open or complete payment itself.
+import { get, post, PersoApiError } from './http_client.mjs';
+
+export const CURRENCIES = ['usd', 'krw'];
+export const DEFAULT_CURRENCY = 'usd'; // international default for new subscriptions; KRW on request
+export const ONE_TIME_CURRENCY = 'usd'; // credit packs are always charged in USD
+// Credits granted per pack — used only to turn a credit shortfall into a pack quantity.
+// Server billing is authoritative.
+export const CREDIT_PER_UNIT = 60;
+export const RETURN_URL = 'https://perso.ai/en/workspace/vt';
+const SUCCESS_PARAMS = 's_seq={spaceSeq}';
+
+// Low → high. Used to find which tiers are an upgrade from the current one.
+const TIER_ORDER = ['free', 'starter', 'creator', 'pro', 'business', 'enterprise'];
+const tierRank = (t) => TIER_ORDER.indexOf(String(t ?? '').toLowerCase());
+
+/** Which purchase flow fits the current plan tier. */
+export function actionForTier(tier) {
+  const t = String(tier ?? '').toLowerCase();
+  if (t === 'starter' || t === 'creator') return 'billing';   // has a subscription → change plan
+  if (t === 'pro' || t === 'business') return 'one-time';      // top self-serve → buy credits
+  if (t === 'enterprise') return 'contact';                    // custom → contact admin, no self-serve
+  return 'checkout';                                           // free/unknown → new subscription
+}
+
+const extractLink = (res) => res?.link ?? res?.result?.link ?? null;
+
+function normalizePlan(tier, p) {
+  return {
+    tier: p.tier ?? tier,
+    planSeq: p.planSeq,
+    planName: p.planName,
+    isCurrentPlan: !!p.isCurrentPlan,
+    isAccessible: p.isAccessible !== false,
+    isSwitchable: p.isSwitchable !== false,
+    priceOptions: (p.priceOptions ?? []).map((o) => ({
+      priceId: o.priceId,
+      price: o.price,
+      priceUnit: o.priceUnit,
+      billingPeriod: o.billingPeriod,
+      discountRate: o.discountRate ?? 0,
+      isCurrentPlan: !!o.isCurrentPlan,
+    })),
+  };
+}
+
+/** Recurring subscription plans for one billing period + currency, one entry per tier. */
+export async function getRecurringPlans(spaceSeq, { billingPeriod, currency }) {
+  const res = await get('/payment/api/v1/plan/groups', {
+    query: { spaceSeq, productType: 'recurring', billingPeriod, currency },
+  });
+  const groups = res?.result ?? {};
+  const plans = [];
+  for (const [tier, arr] of Object.entries(groups)) {
+    const p = Array.isArray(arr) ? arr[0] : null;
+    if (p) plans.push(normalizePlan(tier, p));
+  }
+  return plans;
+}
+
+/** The one-time credit pack (productType=single, USD). Quantity-priced: unitPrice per pack. */
+export async function getCreditProduct(spaceSeq) {
+  const res = await get('/payment/api/v1/plan', {
+    query: { spaceSeq, productType: 'single', currency: ONE_TIME_CURRENCY },
+  });
+  const p = (res?.result ?? [])[0] ?? null;
+  if (!p) return null;
+  const opt = (p.priceOptions ?? [])[0] ?? null;
+  return {
+    planSeq: p.planSeq,
+    planName: p.planName,
+    minQuantity: p.purchaseSeatCountMin ?? 1,
+    maxQuantity: p.purchaseSeatCountMax ?? -1, // -1 = unlimited
+    priceId: opt?.priceId ?? null,
+    unitPrice: opt?.price ?? null,
+    priceUnit: opt?.priceUnit ?? ONE_TIME_CURRENCY,
+    creditPerUnit: CREDIT_PER_UNIT,
+  };
+}
+
+/** Tiers strictly above `currentTier` that can be switched to (for the plan list to offer). */
+export function upgradeCandidates(plans, currentTier) {
+  const rank = tierRank(currentTier);
+  return plans.filter((p) =>
+    tierRank(p.tier) > rank && p.tier !== 'enterprise' && p.isAccessible && p.isSwitchable && !p.isCurrentPlan);
+}
+
+/** Find a tier's price option for the exact billing period (null if that tier has no option for it). */
+export function findPriceOption(plans, tier, billingPeriod) {
+  const plan = plans.find((p) => String(p.tier).toLowerCase() === String(tier).toLowerCase());
+  if (!plan) return null;
+  const opt = plan.priceOptions.find((o) => o.billingPeriod === billingPeriod);
+  return opt ? { planSeq: plan.planSeq, plan, opt } : null;
+}
+
+/** The billing period of the current subscription (billing requires the target to match it). */
+export function currentBillingPeriod(plans) {
+  for (const p of plans) {
+    const cur = p.priceOptions.find((o) => o.isCurrentPlan);
+    if (cur) return cur.billingPeriod;
+  }
+  return null;
+}
+
+/** Credit packs needed to cover a shortfall (each pack = CREDIT_PER_UNIT credits). */
+export function recommendCredits(shortfall) {
+  const quantity = Math.max(1, Math.ceil(Number(shortfall) / CREDIT_PER_UNIT));
+  return { quantity, credits: quantity * CREDIT_PER_UNIT };
+}
+
+// --- link generation (each returns a Stripe URL string) ---
+
+/** Free → new subscription. */
+export async function createCheckoutLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/checkout', {
+    body: {
+      priceId, planSeq, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** Existing subscriber → change plan (Stripe billing-portal preview; body is just these three). */
+export async function createBillingLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/billing', { body: { priceId, planSeq, spaceSeq } });
+  return extractLink(res);
+}
+
+/** Subscriber → buy N credit packs (one-time checkout, USD). */
+export async function createOneTimeLink({ spaceSeq, priceId, planSeq, quantity }) {
+  const res = await post('/payment/api/v1/charge/checkout/one-time', {
+    body: {
+      priceId, planSeq, quantity, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** PAY4052 = Stripe session creation failed — for an existing subscriber this usually means the priceId's
+ *  currency (or period) doesn't match the live subscription, so callers try the preferred currency then
+ *  fall back to the other. */
+export const isCurrencyMismatch = (err) => err instanceof PersoApiError && err.code === 'PAY4052';
+
+/** Run `fn(currency)` for the preferred currency, falling back to the other on a currency mismatch. */
+export async function withCurrencyFallback(preferred, fn) {
+  const order = preferred === 'krw' ? ['krw', 'usd'] : ['usd', 'krw'];
+  let lastErr = null;
+  for (const currency of order) {
+    try { return { currency, result: await fn(currency) }; }
+    catch (e) { if (isCurrencyMismatch(e)) { lastErr = e; continue; } throw e; }
+  }
+  throw lastErr;
+}

package/skills/dubbing/lib/messages.mjs

@@ -11,29 +11,23 @@ export const UTM_PARAMS =
   `utm_source=${UTM_SOURCE}&utm_medium=agent-skill&utm_campaign=perso-dubbing&utm_content=v${CLIENT_VERSION}`;
 export const withUtm = (url) => url + (url.includes('?') ? '&' : '?') + UTM_PARAMS;
 
-// free/starter have no credit purchase, so only a plan upgrade is suggested.
-const LOW_TIERS = new Set(['free', 'starter']);
-
 export const messages = {
-  // Out-of-usage guidance. Depending on planTier: free/starter get upgrade-only, others get both upgrade and credits.
+  // Out-of-usage guidance. The agent can generate a direct Stripe link via scripts/billing.mjs, which
+  // routes by the current plan tier (free → subscribe · starter/creator → change plan · pro/business → credits).
   //   { planTier, remainingQuota, remainingNote, resumeHint, note }
   quotaExceeded: ({ planTier, remainingQuota, remainingNote, resumeHint, note } = {}) => {
-    const isLow = LOW_TIERS.has(String(planTier ?? '').toLowerCase());
     const status =
       `   Current plan: ${planTier ?? 'unknown'} · Credits left: ${remainingQuota ?? '?'}` +
       (remainingNote ? ` · Remaining: ${remainingNote}` : '');
-    const lines = [
+    return [
       'Out of usage/credits — only part of the work completed. The finished items are delivered above.',
       status,
       ...(note ? [note] : []),
       '',
-    ];
-    if (isLow) {
-      lines.push('To continue, upgrade your plan:', `  → ${withUtm(PRICING_URL)}`);
-    } else {
-      lines.push('To continue, upgrade your plan or buy more credits (Get credits), then run again:', `  → ${withUtm(SUBSCRIPTION_URL)}`);
-    }
-    if (resumeHint) lines.push(`  Resume: ${resumeHint}`);
-    return lines.join('\n');
+      'To continue you can generate a payment link (routes by plan: subscribe / change plan / buy credits):',
+      '  → node scripts/billing.mjs options   (add --shortfall <estimated remaining credits> for a recommendation)',
+      '  Then give the returned Stripe link to the user to complete payment in their browser — never pay on their behalf.',
+      ...(resumeHint ? [`  Resume after topping up: ${resumeHint}`] : []),
+    ].join('\n');
   },
 };

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/split.mjs

@@ -17,16 +17,23 @@ const MAX_DEPTH = 4;
 const SEG_MARGIN_MS = 2000; // SEG = cap − GOP − margin: a safety buffer to stay below the cap
 const MIN_SEG_MS = 3000;    // if SEG is smaller than this (GOP too large relative to the cap), lossless is impossible → re-encode fallback
 
+/** Thrown at depth 0 when a split is required but the user hasn't authorized it yet (no allowSplit).
+ *  Carries what the caller needs to build the confirmation prompt: { reason:'length'|'size', limitMs?, actualMs?, actualBytes? }. */
+export class SplitConfirmNeeded extends Error {
+  constructor(details) { super('split confirmation required'); this.name = 'SplitConfirmNeeded'; this.details = details; }
+}
+
 /** @returns {{chunks:Array<{index,source,path?,sourceUrl?,mediaSeq?,startMs?,endMs?}>, notice:string|null}} */
 export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
   const log = hooks.log ?? (() => {});
   const notify = hooks.notify ?? (() => {}); // user-facing milestones (split start, etc.)
+  const allowSplit = hooks.allowSplit ?? false; // false → stop and ask before the first split (SplitConfirmNeeded)
   if (prepared.source === 'external') {
     return { chunks: [{ index: 0, source: 'external', sourceUrl: prepared.sourceUrl }], notice: null };
   }
 
   const localPath = prepared.localPath ?? prepared.path;
-  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify);
+  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify, allowSplit);
   // carry each leaf's absolute boundaries (startMs/endMs) on the chunk → on resume, re-cut only that segment from the original.
   // when split, number the title _01,_02… → in the Perso project list, distinguish pieces of the same original (a single piece keeps the original name).
   const baseTitle = (prepared.originalName ?? basename(localPath)).replace(/\.[^.]+$/, '');
@@ -43,12 +50,13 @@ export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
  * startMs/spanMs are absolute positions relative to the original (an unsplit whole leaf has endMs=null).
  * Side optimization: a size overflow can be known in advance via local stat, so split a huge file directly instead of uploading it whole.
  */
-async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}) {
+async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}, allowSplit = true) {
   if (depth < MAX_DEPTH) {
     const { size } = await stat(localPath);
-    if (size > SIZE_CAP) { // size overflow → split before uploading
+    if (size > SIZE_CAP) { // size overflow → split before uploading (known locally, so no upload is wasted)
+      if (depth === 0 && !allowSplit) throw new SplitConfirmNeeded({ reason: 'size', actualBytes: size });
       log('The file is large, so the video is processed in parts. Cutting and merging takes a little while.');
-      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify);
+      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify, allowSplit);
     }
   }
   try {
@@ -59,14 +67,27 @@ async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = n
     const code = e instanceof PersoApiError ? e.code : null;
     if (code !== 'F4008' && code !== 'F4004') throw e; // errors other than length/size are rethrown as-is
     if (depth >= MAX_DEPTH) throw new Error(`Split limit exceeded (depth ${depth}) — cannot upload`);
+    if (depth === 0 && !allowSplit) throw await splitConfirmFor(code, e, localPath);
     log('The video exceeds the length/size limit, so it is processed in parts. Cutting and merging takes a little while.');
     const lengthCapMs = code === 'F4008' ? Number(e.data?.maxLengthMs) : Infinity;
-    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify);
+    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify, allowSplit);
+  }
+}
+
+// Build the confirmation error for a length (F4008) or size (F4004) rejection, best-effort filling the actual value.
+async function splitConfirmFor(code, err, localPath) {
+  if (code === 'F4008') {
+    let actualMs = null;
+    try { ({ durationMs: actualMs } = await probe(localPath)); } catch { /* ffmpeg absent → omit the actual length */ }
+    return new SplitConfirmNeeded({ reason: 'length', limitMs: Number(err.data?.maxLengthMs) || null, actualMs });
   }
+  let actualBytes = null;
+  try { ({ size: actualBytes } = await stat(localPath)); } catch { /* omit the actual size */ }
+  return new SplitConfirmNeeded({ reason: 'size', actualBytes });
 }
 
 /** Split localPath by the length/size limit and recursively upload each piece. baseStartMs is the absolute offset relative to the original. */
-async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}) {
+async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}, allowSplit = true) {
   ensureFfmpeg(); // install only when cutting is confirmed
   if (depth === 0) notify('Splitting — the video exceeds the length/size limit, so it is processed in parts.'); // user-facing
   const { durationMs, sizeBytes } = await probe(localPath);
@@ -79,7 +100,7 @@ async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCa
   for (let i = 0; i < parts.length; i++) {
     log(`Uploading piece ${i + 1}/${parts.length}...`);
     const p = parts[i];
-    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify)));
+    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify, allowSplit)));
   }
   return out;
 }