yt-briefing 0.3.2 → 0.4.0

package/.claude/skills/yt-transcribe/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: yt-transcribe
+description: Fetch a single YouTube video's transcript and summarize it. One-shot — paste a URL or video ID, get a journalist-grade summary. Same transcript engine (and WARP proxy support) as the /yt briefing loop; no channels, no state, no rating.
+argument-hint: URL or VIDEO_ID. Optional --lang pl|en|auto (defaults to auto).
+---
+
+## Step 1 — Fetch the transcript
+
+```bash
+bun run src/yt-transcript.ts <VIDEO_ID_OR_URL> --lang <lang>
+```
+
+- First argument: URL or VIDEO_ID straight from the user — the script parses both formats (`youtube.com/watch?v=…`, `youtu.be/…`, or a bare 11-char ID).
+- `--lang` selects which **caption track to fetch** (the input), not the summary language. `auto`
+  by default (best available track); pass `pl` / `en` only if the user wants a specific track.
+- The transcript goes to **stdout**; stderr carries diagnostics. Run it bare — no redirects.
+
+Exit codes — the message you show the user must match the real cause. Never report a
+tooling failure as "no subtitles". When the code is non-zero, read the script's stderr
+and surface that actual reason; do not paraphrase it away.
+- `0` — transcript on stdout → continue to Step 2.
+- `1` → the video genuinely has no subtitles. Tell the user exactly that and stop.
+- `2` → YouTube rate-limit / IP block (common on datacenter/VPS IPs). Tell the user and
+        stop; it's transient. Recovery: route fetches through a proxy — see
+        `docs/warp-proxy.md` (set `YT_BRIEFING_PROXY`).
+- `3` → tooling/integration failure (yt-dlp missing, fetch error, unavailable or private
+        video, empty/unparseable track, bad input). This is NOT a missing-captions case.
+        Show the stderr line verbatim so the user sees the real problem, and stop.
+
+---
+
+## Step 2 — Summary
+
+Read the transcript from the tool result and respond as a narrative.
+
+- **Header:** title, author, date
+- One introductory sentence
+- One paragraph per significant thread — a bold label + continuous prose, concrete facts. Preserve the logic and rhetoric of the original.
+- Verdict: what's strong, what's weak, whether it was worth it
+
+Style:
+- an intelligent journalist — not like an AI assistant summarizing an article
+- no generalities, always specifics: what was the thesis, what was the argument
+- if the material has a clear host and guests, show that in the text
+
+**Language:** Read `data/config.json` → `output_lang` once and write the summary in that
+language — the same language chosen at onboarding that `/yt` uses. Order of precedence:
+(1) a language the user explicitly asks for in this request wins; (2) otherwise `output_lang`
+from config; (3) only if config is missing, match the language of the video. This is the
+**output** language and is independent of `--lang` (which only picks the caption track to
+fetch). Don't mix languages: write fully in the target language and insert foreign words only
+when they are (a) a proper name of a technology/product, or (b) an established technical term
+with no natural equivalent (API, REST, JSON, webhook, endpoint). Translate everything else.
+
+---
+
+## Rules
+
+- **Transcripts:** never paste the raw transcript into chat — the summary is the artifact.
+- **One-shot, stateless:** this skill reads no channels, writes no state, asks for no rating.
+  It is independent of the `/yt` briefing loop, though it shares the same transcript engine
+  and proxy. For the recurring channel briefing, use `/yt` instead.

package/README.md

@@ -64,8 +64,24 @@ npx yt-briefing list                                        # show the current l
 ## Run it
 
 Open your project in Claude Code or Cursor and run `/yt`. If it's not listed, start a fresh
-session. To install the skill again for another tool or project, run
-`npx yt-briefing install-skill`.
+session. To install the skills again for another tool or project, run
+`npx yt-briefing install-skill` (it installs both `/yt` and `/yt-transcribe`).
+
+## One-off: transcribe a single video
+
+Just want one video summarized — no channels, no queue, no rating? Run `/yt-transcribe` and
+paste a URL or video ID. It pulls that video's transcript and writes a journalist-grade
+summary in the language you chose at setup (the same `output_lang` as `/yt`). Want a one-off in
+another language? Just say so when you run it (e.g. `/yt-transcribe <url> in German`) — it
+won't change your setup. `--lang pl|en` is separate — it picks which caption track to fetch,
+not the summary language. Same transcript engine and proxy as the briefing loop, so on a
+server it benefits from the same [WARP proxy](#running-on-a-vps).
+
+The skill is installed alongside `/yt` by `init` / `install-skill`. From the plain CLI:
+
+```bash
+npx yt-briefing transcribe <url-or-id> --lang auto   # prints the transcript to stdout
+```
 
 ## Providers
 

package/dist/bootstrap.js

@@ -16,7 +16,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { DATA_DIR, BASE_DIR, PKG_ROOT, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, ENV_PATH, profilePath, } from "./lib/paths.js";
-import { AGENTS, installSkill, projectSkillDir, customSkillDirDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd } from "./lib/skill-install.js";
 import { question } from "./lib/prompt.js";
 import { normalizeHandle, slugify, serializeChannels, serializeState, profileBody, baselineStateRow } from "./lib/channels.js";
 const ask = (q, def = '') => {
@@ -114,7 +114,7 @@ function main() {
     console.log('       1) Claude Code      2) Cursor      3) Custom folder (any other agent)\n');
     const agentKey = ask('  Your agent', '1');
     // For a custom target, ask the folder now (keeps all prompts in the interactive block).
-    const customDir = AGENTS[agentKey] ? '' : ask('  Folder to install the skill into', customSkillDirDefault());
+    const customDir = AGENTS[agentKey] ? '' : ask('  Skills folder to install into', customSkillsRootDefault());
     // 7. Write everything --------------------------------------------------------
     mkdirSync(CHANNELS_DIR, { recursive: true });
     // .env
@@ -148,23 +148,24 @@ function main() {
     console.log(`    ${CHANNELS_MD}`);
     console.log(`    ${STATE_MD}`);
     console.log(`    ${channels.length} profile(s) in ${CHANNELS_DIR}/`);
-    // Install the /yt skill for the chosen agent (step 6), into THIS project — process.cwd(),
-    // i.e. wherever you ran the command (the package clone in dev, or your own project when the
-    // package is a dependency). The command baked in is the shipped `bun run src` only for the
-    // dev-in-clone case; otherwise the compiled `dist/` command (so a consumed package works).
+    // Install the /yt + /yt-transcribe skills for the chosen agent (step 6), into THIS project —
+    // process.cwd(), i.e. wherever you ran the command (the package clone in dev, or your own
+    // project when the package is a dependency). The command baked in is the shipped `bun run src`
+    // only for the dev-in-clone case; otherwise the compiled `dist/` command (so a consumed package works).
     const agent = AGENTS[agentKey];
     try {
-        const target = agent
-            ? installSkill(projectSkillDir(agentKey, process.cwd()), /* dist */ !isPackageDevCwd())
-            : installSkill(customDir, /* dist */ true);
-        console.log(`    /yt skill → ${target}`);
+        const targets = agent
+            ? installSkills(projectSkillsRoot(agentKey, process.cwd()), /* dist */ !isPackageDevCwd())
+            : installSkills(customDir, /* dist */ true);
+        for (const t of targets)
+            console.log(`    skill → ${t}`);
     }
     catch (e) {
-        console.log(`  ! Couldn't install the skill (${e.message}) — run  yt-briefing install-skill  later.`);
+        console.log(`  ! Couldn't install the skills (${e.message}) — run  yt-briefing install-skill  later.`);
     }
     console.log('\n  Next:');
     console.log(`    1. Open this folder in ${agent ? agent.name : 'your agent'}.`);
-    console.log('    2. Start a new chat and type  /yt');
+    console.log('    2. Start a new chat and type  /yt  (or  /yt-transcribe <url>)');
     console.log('\n  No agent? Run it in the terminal instead — see the README.\n');
 }
 try {

package/dist/install-skill.js

@@ -1,51 +1,54 @@
 #!/usr/bin/env node
 /**
- * install-skill — copy the `/yt` skill into a coding agent's skills directory so the
- * agent detects it. For any target that isn't this package under Bun, the command is baked to
- * `"<this runtime>" "<abs>/dist/X.js"` (the compiled build), so it works no matter the agent's
- * working directory or runtime (the engine resolves data/.env from its own location).
+ * install-skill — copy this package's skills (`/yt` + `/yt-transcribe`) into a coding agent's
+ * skills directory so the agent detects them. For any target that isn't this package under Bun,
+ * each command is baked to `"<this runtime>" "<abs>/dist/X.js"` (the compiled build), so it works
+ * no matter the agent's working directory or runtime (the engine resolves data/.env from its own
+ * location).
  *
  *   yt-briefing install-skill        # interactive: pick agent + scope
  *
- * `bun run init` already installs this skill into the project as its final step; this
+ * `bun run init` already installs these skills into the project as its final step; this
  * standalone command is for re-installing, a different project, or a second agent. There is
- * deliberately no home-global install — the skill lives with the project that uses it.
+ * deliberately no home-global install — the skills live with the project that uses them.
  *
  * Both Claude Code and Cursor load `SKILL.md` skills and invoke them as `/<name>`.
- * Cursor also reads `.claude/skills/` for compatibility, so the copy this package already
- * ships often works in both — this command just (re)places it where you want.
+ * Cursor also reads `.claude/skills/` for compatibility, so the copies this package already
+ * ships often work in both — this command just (re)places them where you want.
  */
-import { AGENTS, installSkill, projectSkillDir, customSkillDirDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd } from "./lib/skill-install.js";
 import { question } from "./lib/prompt.js";
 const ask = (q, def = '') => question(def ? `${q} [${def}]:` : `${q}:`).trim() || def;
-function done(target) {
-    console.log(`\n  ✓ Installed → ${target}`);
-    console.log('  Start a fresh agent session, then run  /yt\n');
+function done(targets) {
+    console.log('\n  ✓ Installed:');
+    for (const t of targets)
+        console.log(`      ${t}`);
+    console.log('  Start a fresh agent session, then run  /yt  or  /yt-transcribe\n');
 }
 // 1) which agent → which skills subdir
-console.log('\n  Install the /yt skill — which agent?\n');
+console.log('\n  Install the /yt + /yt-transcribe skills — which agent?\n');
 console.log('    1) Claude Code');
 console.log('    2) Cursor   (also reads Claude\'s .claude/skills)');
 console.log('    3) Custom folder (any other agent)\n');
 const agentKey = ask('  Agent', '1');
 const agent = AGENTS[agentKey];
-// 3) Custom — write SKILL.md straight into a folder the user names (their agent's skills dir).
-// Arbitrary location → bake the absolute dist command so it works whatever the agent's cwd is.
+// 3) Custom — write the skills straight into a skills root the user names (their agent's dir).
+// Arbitrary location → bake the absolute dist commands so they work whatever the agent's cwd is.
 if (!agent) {
-    done(installSkill(ask('  Folder to install the skill into', customSkillDirDefault()), true));
+    done(installSkills(ask('  Skills folder to install into', customSkillsRootDefault()), true));
     process.exit(0);
 }
 // 2) Known agent → which project (default: the current folder). No home-global option by
-// design — the skill is always scoped to a project that uses it.
+// design — the skills are always scoped to a project that uses them.
 console.log(`\n  ${agent.name} — which project?\n`);
 console.log('    1) This project (current folder) — recommended');
 console.log('    2) Another project folder\n');
 if (ask('  Where', '1') === '2') {
-    // A different project → the agent's cwd won't be the package, so bake the absolute dist command.
-    done(installSkill(projectSkillDir(agentKey, ask('  Project folder', process.cwd())), true));
+    // A different project → the agent's cwd won't be the package, so bake the absolute dist commands.
+    done(installSkills(projectSkillsRoot(agentKey, ask('  Project folder', process.cwd())), true));
 }
 else {
     // Current folder: shipped `bun run src` only when developing in the package clone under Bun;
-    // otherwise (incl. consuming the package as a dependency) bake the compiled dist command.
-    done(installSkill(projectSkillDir(agentKey, process.cwd()), !isPackageDevCwd()));
+    // otherwise (incl. consuming the package as a dependency) bake the compiled dist commands.
+    done(installSkills(projectSkillsRoot(agentKey, process.cwd()), !isPackageDevCwd()));
 }

package/dist/lib/skill-install.js

@@ -1,12 +1,17 @@
 /**
- * skill-install — place the `/yt` SKILL.md into a coding agent's skills directory.
+ * skill-install — place this package's SKILL.md files into a coding agent's skills directory.
  *
  * Shared by the onboarding wizard (`bootstrap.ts`, final step) and the standalone
- * `install-skill.ts` command, so both write the skill identically.
+ * `install-skill.ts` command, so both write the skills identically.
  *
- * The shipped SKILL.md uses `bun run src/X.ts` — the dev shortcut: it works when the agent's
- * cwd IS the package folder AND the runtime is Bun (which runs TypeScript directly). That's
- * true for the publisher's own day-to-day use, so it stays the default.
+ * The package ships TWO skills, each at `.claude/skills/<name>/SKILL.md`:
+ *   yt            — the recurring channel briefing loop (sweep + rate).
+ *   yt-transcribe — one-shot: a single video's transcript → summary.
+ * Both are installed together so an agent gets the whole toolset in one step.
+ *
+ * The shipped SKILL.md files use `bun run src/X.ts` — the dev shortcut: it works when the
+ * agent's cwd IS the package folder AND the runtime is Bun (which runs TypeScript directly).
+ * That's true for the publisher's own day-to-day use, so it stays the default.
  *
  * For everyone else — a Node user, or any install whose cwd won't be the package — we bake an
  * absolute, runtime-correct command instead: `"<this runtime>" "<abs>/dist/X.js"`. The runtime
@@ -20,6 +25,8 @@ import { join, resolve } from 'node:path';
 import { PKG_ROOT, DATA_DIR } from "./paths.js";
 /** Compiled output dir — what a baked (dist) skill command points the runtime at. */
 const DIST_DIR = join(PKG_ROOT, 'dist');
+/** The skills this package ships — each lives at `.claude/skills/<name>/SKILL.md`. */
+export const SKILLS = ['yt', 'yt-transcribe'];
 /** True when the installer itself is running under Bun (vs plain Node). */
 export const isBun = process.versions.bun != null;
 /**
@@ -30,23 +37,25 @@ export const isBun = process.versions.bun != null;
  * compiled `dist/` command instead. This detects that one dev-in-clone case.
  */
 export const isPackageDevCwd = () => isBun && resolve(process.cwd()) === PKG_ROOT;
-export const SOURCE = join(PKG_ROOT, '.claude/skills/yt/SKILL.md');
-/** Agent key → display name + the skills subdirectory it scans. */
+/** Source path of a shipped skill's SKILL.md, by skill name. */
+export const skillSource = (name) => join(PKG_ROOT, '.claude', 'skills', name, 'SKILL.md');
+/** Agent key → display name + the skills ROOT directory it scans (skills install under it). */
 export const AGENTS = {
-    '1': { name: 'Claude Code', sub: join('.claude', 'skills', 'yt') },
-    '2': { name: 'Cursor', sub: join('.cursor', 'skills', 'yt') },
+    '1': { name: 'Claude Code', sub: join('.claude', 'skills') },
+    '2': { name: 'Cursor', sub: join('.cursor', 'skills') },
 };
 /**
- * The shipped SKILL.md. `dist=false` (default) returns it verbatim — the `bun run src/X.ts`
- * dev form, correct only when cwd is the package AND the runtime is Bun. `dist=true` rewrites
- * for the consumed case: engine commands become `"<process.execPath>" "<abs>/dist/X.js"` (this
- * machine's runtime, Node or Bun, against the compiled build, so they run from any cwd), and the
- * bare `data/…` paths the agent reads (e.g. `data/config.json`) become the absolute `DATA_DIR`.
- * In dev the agent's cwd IS the package so `data/` resolves; when consumed, DATA_DIR moves to
- * `<project>/.yt-briefing/data`, so the dev-relative paths would miss — hence the rewrite.
+ * One shipped skill's SKILL.md. `dist=false` (default) returns it verbatim — the
+ * `bun run src/X.ts` dev form, correct only when cwd is the package AND the runtime is Bun.
+ * `dist=true` rewrites for the consumed case: engine commands become
+ * `"<process.execPath>" "<abs>/dist/X.js"` (this machine's runtime, Node or Bun, against the
+ * compiled build, so they run from any cwd), and the bare `data/…` paths the agent reads (e.g.
+ * `data/config.json`) become the absolute `DATA_DIR`. In dev the agent's cwd IS the package so
+ * `data/` resolves; when consumed, DATA_DIR moves to `<project>/.yt-briefing/data`, so the
+ * dev-relative paths would miss — hence the rewrite.
  */
-export function skillBody(dist = false) {
-    const raw = readFileSync(SOURCE, 'utf8');
+export function skillBody(name, dist = false) {
+    const raw = readFileSync(skillSource(name), 'utf8');
     if (!dist)
         return raw;
     const exe = process.execPath;
@@ -54,17 +63,24 @@ export function skillBody(dist = false) {
     return raw
         .replace(/bun run src\/yt-sweep\.ts/g, cmd('yt-sweep'))
         .replace(/bun run src\/yt-rating\.ts/g, cmd('yt-rating'))
+        .replace(/bun run src\/yt-transcript\.ts/g, cmd('yt-transcript'))
         .replace(/data\//g, DATA_DIR + '/');
 }
-/** Write the skill into `dir` (created if needed). Returns the SKILL.md path written. */
-export function installSkill(dir, dist = false) {
-    mkdirSync(dir, { recursive: true });
-    const target = join(dir, 'SKILL.md');
-    writeFileSync(target, skillBody(dist), 'utf8');
-    return target;
+/**
+ * Write every shipped skill into `root`, each under its own `<name>/SKILL.md` subdir
+ * (created if needed). Returns the SKILL.md paths written, in `SKILLS` order.
+ */
+export function installSkills(root, dist = false) {
+    return SKILLS.map((name) => {
+        const dir = join(root, name);
+        mkdirSync(dir, { recursive: true });
+        const target = join(dir, 'SKILL.md');
+        writeFileSync(target, skillBody(name, dist), 'utf8');
+        return target;
+    });
 }
-/** The agent's skills directory inside a project folder (the project you open in the agent). */
-export const projectSkillDir = (agentKey, projectDir) => join(projectDir, AGENTS[agentKey].sub);
+/** The agent's skills ROOT inside a project folder (the project you open in the agent). */
+export const projectSkillsRoot = (agentKey, projectDir) => join(projectDir, AGENTS[agentKey].sub);
 /** Suggested target for a "custom" (any other agent) install — the open `.agents` convention,
  *  rooted at the user's current project (not the package, which may be in node_modules). */
-export const customSkillDirDefault = () => join(process.cwd(), '.agents', 'skills', 'yt');
+export const customSkillsRootDefault = () => join(process.cwd(), '.agents', 'skills');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "A self-learning YouTube briefing engine: it sweeps the channels you follow, filters noise in two stages (title, then transcript), summarizes the rest in your language, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {