yt-briefing 0.3.2 → 0.5.0

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

@@ -0,0 +1,53 @@
+---
+name: yt-search
+description: Research a topic across YouTube — describe an intent, the engine expands it into search queries, ranks results against your intent, then lazily yields ONE video at a time with a rich summary. You keep or skip each; at the end it synthesizes a comparison from everything you kept. Same transcript engine + proxy as /yt; lazy on purpose (no transcript bursts → no IP block). Summaries and prompts use the language chosen at onboarding.
+argument-hint: A descriptive intent in quotes, e.g. "which terminal for coding with Claude Code". Optional --max N, --since YYYY-MM-DD, --queries 1..3.
+---
+
+## How it works
+
+`src/yt-search.ts` is the whole engine: intent → query expansion (LLM) → `search.list` → re-rank against the intent on metadata only (no transcript) → **lazy** one-candidate-at-a-time yield with a rich summary → record keep/skip → on demand synthesize a comparison from everything kept. Matching is **descriptive, not exact-keyword** — YouTube ranks by relevance and the LLM bridges intent→query and filters noise. This skill is a thin loop: paste the summary, collect keep/skip, show the final comparison. It runs no filters and formats nothing itself.
+
+**Lazy on purpose:** one transcript per step, never a burst — a burst looks like scraping and gets the IP blocked (same reason `/yt` is lazy). Run the engine bare — stdout is a single JSON line, stderr empty; never redirect.
+
+## Language
+
+Read `data/config.json` → `output_lang` once at the start. Phrase the question text and option descriptions in that language. The two button labels stay the short English words `Keep` / `Skip`. Summaries and the final comparison are already written in `output_lang` by the engine — paste them verbatim.
+
+## Loop
+
+```
+out = JSON.parse(`bun run src/yt-search.ts "<intent from the user>" --reset`)   // first call
+while true:
+  out.status:
+    "error"           → show out.error verbatim, stop
+    "no_results"      → tell the user nothing relevant was found, stop
+    "rate_limited"    → transcript fetch blocked (datacenter IP) — tell the user, stop; recovery in README.md → Running on a VPS
+    "decision_needed" → steps A–C
+    "done"            → step D
+```
+
+**On `decision_needed`:**
+
+- **A.** Take `out.summary` (markdown) and `out.pending` (`{videoId,title,channelTitle,publishedAt,position,total}`).
+- **B.** In the SAME turn, as your chat text (NOT command output — the UI doesn't show it), paste `summary` **verbatim** — no paraphrase, no shortening. Optionally prefix one line like `Wynik {position}/{total}`. The user must see it before the popup.
+- **C.** In the same message call `AskUserQuestion` — 1 call, 1 question, phrased in `output_lang`:
+  - Question e.g. "Brać pod uwagę w porównaniu?" with two options: **Keep** = include this video in the final comparison; **Skip** = drop it.
+  - **Other** is the stop channel: if the user types `stop` (case-insensitive, trimmed) or dismisses the popup (✕) → **end the loop early** and go to step D (compare what's kept so far).
+  - Then act:
+    - Keep → `bun run src/yt-search.ts --keep`
+    - Skip → `bun run src/yt-search.ts --skip`
+    - stop/dismissed → `bun run src/yt-search.ts --compare` (skip straight to D)
+  - The script reads the pending candidate from cache; pass only `--keep` / `--skip` / `--compare`. Its JSON becomes the next `out` — back to the top of the loop.
+
+**On `done` (step D):**
+
+- If `out.kept > 0` → run `out = JSON.parse(\`bun run src/yt-search.ts --compare\`)`; when it returns `status:"compare"`, paste `out.comparison` **verbatim** as your chat text (it's the artifact — a decision-grade comparison in `output_lang`). Stop.
+- If `out.kept == 0` → tell the user nothing was kept, so there's nothing to compare. Stop.
+
+## Rules
+
+- **Verbatim:** paste `summary` and `comparison` exactly as returned; never paste a raw transcript.
+- **Language:** question text + option descriptions follow `output_lang`; button labels stay `Keep` / `Skip`.
+- **Cost awareness:** each search runs `search.list` (100 quota units/query, up to `--queries`). Don't silently re-run `--reset` in a loop. A bare resume (no `--reset`) continues the same ranked queue without new searches.
+- **Stateless triage:** this is independent of `/yt` (no channels, no ratings). For the recurring channel briefing use `/yt`; for one video use `/yt-transcribe`.

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

@@ -24,7 +24,8 @@ the last one left off.
 You'll need Node 18+ or Bun, a YouTube Data API v3 key, an LLM key (a
 [free Gemini key](https://aistudio.google.com/apikey) works, see [Providers](#providers)), and
 a tool that runs skills: [Claude Code](https://claude.com/claude-code),
-[Cursor](https://cursor.com), or anything else that loads `SKILL.md`.
+[Cursor](https://cursor.com), [Codex](https://developers.openai.com/codex), or anything else
+that loads the standard `SKILL.md` (Agent Skills — 30+ agents).
 
 1. Install yt-dlp (it pulls the subtitles):
 
@@ -61,11 +62,45 @@ npx yt-briefing remove @handle                              # also deletes its l
 npx yt-briefing list                                        # show the current list
 ```
 
+## 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.
+
+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
+```
+
+## Research a topic across YouTube
+
+Want to know what YouTube says about something — and get an actual comparison, not a pile of
+links? Run `/yt-search` and describe the intent, e.g. `which terminal for coding with Claude
+Code`. The matching is **descriptive, not exact keywords**: an LLM turns your intent into search
+queries, then ranks the results against what you actually meant (on titles/descriptions — no
+transcripts yet). Then it hands you **one video at a time** with a rich summary; you **Keep** or
+**Skip** each. At the end it synthesizes a **comparison** from everything you kept.
+
+It's lazy on purpose — one transcript per step, never a burst (a burst gets your IP blocked, same
+as `/yt`). Summaries and the comparison use the language you chose at setup.
+
+```bash
+yt-briefing search "<intent>" [--max N] [--queries 1..3] [--since YYYY-MM-DD]   # JSON status line
+```
+
+> Each search calls the YouTube `search.list` endpoint, which costs **100 quota units per query**
+> (plain reads cost 1; the daily free quota is 10,000). `--queries` (default 2) caps how many.
+
 ## 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 `/yt`, `/yt-transcribe`, and `/yt-search`).
 
 ## Providers
 
@@ -94,9 +129,9 @@ summarizing the next video while you rate the current one, so the following step
 ready with no wait. An agent's turn-by-turn loop cannot prefetch like that, and every step pays
 its own cold start, which adds up across a whole queue.
 
-Compatibility. A standard API plus a small skill means one engine runs everywhere: Claude Code,
-Cursor, any other tool that loads a skill, or the plain CLI. A tool-native approach would tie it
-to that one tool and one model.
+Compatibility. A standard API plus a standard `SKILL.md` means one engine runs everywhere: Claude
+Code, Cursor, Codex, any other Agent-Skills-compatible tool, or the plain CLI. A tool-native
+approach would tie it to that one tool and one model.
 
 ## Why one transcript at a time
 

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 = '') => {
@@ -108,13 +108,14 @@ function main() {
     // 6. Coding agent ------------------------------------------------------------
     // Place the skill INTO THIS PROJECT (the package folder you open in the agent) — never a
     // home-global dir (that's the npm -g antipattern: machine-wide, invisible, easy to forget).
-    // Claude Code reads .claude/skills/ (already shipped here); Cursor reads .cursor/skills/.
-    // 1/2 = known agents; 3 = any other agent (a project folder you name).
-    console.log('\n  6) Which agent will you run /yt in?');
-    console.log('       1) Claude Code      2) Cursor      3) Custom folder (any other agent)\n');
+    // SKILL.md is the cross-agent standard, so the shipped skill runs in any compatible agent —
+    // we just install it into that agent's skills dir (.claude/skills, .cursor/skills, .codex/skills).
+    // 1/2/3 = known agents; 4 = any other compatible agent (a project folder you name).
+    console.log('\n  6) Which agent will you run /yt in?  (it ships a standard Agent Skill — any compatible agent works)');
+    console.log('       1) Claude Code   2) Cursor   3) Codex   4) 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 +149,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/cli.js

@@ -12,6 +12,7 @@
  *   yt-briefing sweep [--reset]            advance one step; prints a JSON status line
  *   yt-briefing rate --rating 0|1 [...]    record a rating for the pending video
  *   yt-briefing transcribe <url|id>        print a single video's transcript
+ *   yt-briefing search "<intent>" [...]    topic search → lazy triage → compare (JSON status line)
  */
 import { spawnSync } from 'node:child_process';
 import { script } from "./lib/paths.js";
@@ -24,6 +25,7 @@ const TARGETS = {
     sweep: 'yt-sweep',
     rate: 'yt-rating',
     transcribe: 'yt-transcript',
+    search: 'yt-search',
 };
 const CHANNEL_ACTIONS = new Set(['add', 'remove', 'list']);
 let argv = null;
@@ -32,7 +34,7 @@ if (cmd && CHANNEL_ACTIONS.has(cmd))
 else if (cmd && TARGETS[cmd])
     argv = [script(TARGETS[cmd]), ...rest];
 if (!argv) {
-    console.error('Usage: yt-briefing <init|install-skill|add|remove|list|sweep|rate|transcribe> [args...]');
+    console.error('Usage: yt-briefing <init|install-skill|add|remove|list|sweep|rate|transcribe|search> [args...]');
     process.exit(cmd ? 1 : 0);
 }
 const res = spawnSync(process.execPath, argv, { stdio: 'inherit' });

package/dist/install-skill.js

@@ -1,51 +1,55 @@
 #!/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.
+ * SKILL.md is the cross-agent Agent Skills standard, so the shipped skills run in any compatible
+ * agent (Claude Code, Cursor, Codex, and 30+ others); this command just (re)places them in the
+ * skills dir of whichever agent you pick.
  */
-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');
+console.log('    2) Cursor');
+console.log('    3) Codex');
+console.log('    4) Custom folder (any other compatible 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/paths.js

@@ -47,6 +47,10 @@ export const REST_FILE = join(CACHE_DIR, 'queue-rest.json');
 export const PENDING_FILE = join(CACHE_DIR, 'pending.json');
 export const PREFETCH_FILE = join(CACHE_DIR, 'prefetch.json');
 export const LOG_FILE = join(CACHE_DIR, 'sweep.log');
+// /yt-search (ad-hoc topic search → lazy triage → compare). All throwaway, under .cache/.
+export const SEARCH_QUEUE_FILE = join(CACHE_DIR, 'search-queue.json'); // ranked candidates + cursor
+export const SEARCH_PENDING_FILE = join(CACHE_DIR, 'search-pending.json'); // current candidate awaiting keep/skip
+export const SEARCH_KEPT_FILE = join(CACHE_DIR, 'search-kept.json'); // kept mega-summaries → compare corpus
 /** Absolute path to a channel profile from its slug. */
 export const profilePath = (slug) => join(CHANNELS_DIR, `${slug}.md`);
 /**

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', 'yt-search'];
 /** True when the installer itself is running under Bun (vs plain Node). */
 export const isBun = process.versions.bun != null;
 /**
@@ -30,23 +37,34 @@ 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).
+ *
+ * SKILL.md is the cross-agent Agent Skills standard (Anthropic, Dec 2025), now read by 30+
+ * tools that each scan their own `<agent-home>/skills/` dir. We only need the right directory
+ * per agent — the shipped SKILL.md works unmodified in all of them. The "custom folder" picker
+ * option (no AGENTS entry) covers every other compatible agent (Gemini CLI, Copilot, Windsurf…)
+ * and defaults to the neutral `.agents/skills/` location.
+ */
 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') },
+    '3': { name: 'Codex', sub: join('.codex', '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 +72,25 @@ 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(/bun run src\/yt-search\.ts/g, cmd('yt-search'))
         .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/dist/lib/yt-api.js

@@ -110,6 +110,35 @@ async function enrichWithTypes(videos) {
     }
     return out;
 }
+/**
+ * Free-text video search via `search.list`. YouTube ranks by relevance, so the query can be
+ * descriptive — no exact keyword match required. NOTE: search.list costs 100 quota units per
+ * call (plain reads cost 1), so callers should keep the number of queries small.
+ *
+ * `since` (ISO date) maps to publishedAfter — useful to cut stale results on fast-moving topics.
+ */
+export async function searchVideos(query, opts = {}) {
+    const { maxResults = 10, since = null } = opts;
+    const params = {
+        part: 'snippet',
+        q: query,
+        type: 'video',
+        order: 'relevance',
+        maxResults: String(Math.min(Math.max(maxResults, 1), 50)),
+    };
+    if (since)
+        params.publishedAfter = new Date(since).toISOString();
+    const data = await get('search', params);
+    return (data.items || [])
+        .filter((it) => it.id?.videoId)
+        .map((it) => ({
+        videoId: it.id.videoId,
+        title: it.snippet?.title ?? '',
+        channelTitle: it.snippet?.channelTitle ?? '',
+        publishedAt: it.snippet?.publishedAt ?? '',
+        description: it.snippet?.description ?? '',
+    }));
+}
 /**
  * List a channel's uploads (newest first). With `enrich` (default true) each video is
  * typed (short/live/longform) and current/upcoming live broadcasts are filtered out.

package/dist/yt-search.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+/**
+ * yt-search.ts — ad-hoc topic search → lazy triage → comparison. The third yt-briefing mode,
+ * sibling to the channel briefing (yt-sweep) and one-shot transcribe (yt-transcript).
+ *
+ * You describe an intent ("which terminal for coding with Claude Code"); the engine:
+ *   1. expands it into a few YouTube search queries (LLM),
+ *   2. runs search.list and merges candidates,
+ *   3. re-ranks candidates against your intent on metadata only — title/channel/description,
+ *      NO transcript yet (cheap; protects the expensive/rate-limited transcript step),
+ *   4. yields ONE candidate at a time with a rich summary, lazily — never a burst of transcript
+ *      fetches (a burst looks like scraping and gets the IP blocked, same reason yt-sweep is lazy),
+ *   5. records your keep/skip decision; kept summaries accumulate in a cache,
+ *   6. on demand synthesizes a comparison across everything you kept.
+ *
+ * Matching is descriptive, not exact-keyword: search.list already ranks by relevance, and the
+ * LLM bridges intent→query (step 1) and filters noise (step 3).
+ *
+ * Usage (the skill / CLI drives these; one JSON line per call):
+ *   yt-search "<intent>" [--reset] [--max N] [--queries N] [--since DATE] [--lang auto]
+ *   yt-search --keep        record the pending candidate, advance, yield next
+ *   yt-search --skip        drop the pending candidate, advance, yield next
+ *   yt-search --compare     synthesize a comparison from everything kept
+ *
+ * Output statuses:
+ *   {"status":"decision_needed","summary":"<md>","pending":{videoId,title,channelTitle,publishedAt,position,total}}
+ *   {"status":"done","kept":N}              queue exhausted — caller runs --compare if kept>0
+ *   {"status":"compare","comparison":"<md>"}
+ *   {"status":"no_results"}                 search returned nothing for the intent
+ *   {"status":"rate_limited"}               transcript fetch blocked (datacenter IP — see docs/warp-proxy.md)
+ *   {"status":"error","error":"<msg>"}      setup/config problem (missing key, etc.)
+ *
+ * Cache (all throwaway, under DATA_DIR/.cache): search-queue.json (ranked candidates + cursor),
+ * search-pending.json (current candidate), search-kept.json (kept summaries = compare corpus).
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import dotenv from 'dotenv';
+import { chat, getModel } from "./lib/llm.js";
+import { outputLang } from "./lib/config.js";
+import { searchVideos } from "./lib/yt-api.js";
+import { PKG_ROOT, ENV_PATH, CACHE_DIR, SEARCH_QUEUE_FILE, SEARCH_PENDING_FILE, SEARCH_KEPT_FILE, script, } from "./lib/paths.js";
+dotenv.config({ path: ENV_PATH });
+mkdirSync(CACHE_DIR, { recursive: true });
+const RUNTIME = process.execPath;
+const LANG = outputLang();
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const flagVal = (f) => {
+    const i = argv.indexOf(f);
+    return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
+};
+// First non-flag token is the intent (only on the initial / --reset call).
+const positional = argv.filter((a, i) => !a.startsWith('--') && !(i > 0 && argv[i - 1].startsWith('--') && argv[i - 1] !== '--reset' && argv[i - 1] !== '--keep' && argv[i - 1] !== '--skip' && argv[i - 1] !== '--compare'));
+const intentArg = positional[0] ?? null;
+const RESET = has('--reset');
+const KEEP = has('--keep');
+const SKIP = has('--skip');
+const COMPARE = has('--compare');
+const MAX = Math.max(1, parseInt(flagVal('--max') || '8', 10));
+const QUERIES = Math.max(1, Math.min(3, parseInt(flagVal('--queries') || '2', 10)));
+const SINCE = flagVal('--since');
+const LANGTRACK = flagVal('--lang') || 'auto';
+function emit(obj) {
+    process.stdout.write(JSON.stringify(obj));
+    process.exit(0);
+}
+const readJSON = (p, fallback) => {
+    if (!existsSync(p))
+        return fallback;
+    try {
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+};
+const writeJSON = (p, v) => writeFileSync(p, JSON.stringify(v));
+const loadQueue = () => readJSON(SEARCH_QUEUE_FILE, null);
+const loadKept = () => readJSON(SEARCH_KEPT_FILE, []);
+/** Fetch a transcript via the sibling script with the launching runtime. Mirrors yt-sweep. */
+function fetchTranscript(videoId) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(RUNTIME, [script('yt-transcript'), videoId, '--lang', LANGTRACK], { cwd: PKG_ROOT, env: { ...process.env } });
+        let stdout = '';
+        p.stdout.on('data', d => { stdout += d.toString(); });
+        p.stderr.resume();
+        p.on('close', code => resolve({ stdout, code: code ?? 1 }));
+        p.on('error', reject);
+    });
+}
+/** Strip ```fences``` and slice the outermost JSON array from an LLM reply. */
+function parseJsonArray(out) {
+    const start = out.indexOf('['), end = out.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    try {
+        return JSON.parse(out.slice(start, end + 1));
+    }
+    catch {
+        return null;
+    }
+}
+// ---------- stage 1: intent → search queries ----------
+async function expandQueries(intent) {
+    const prompt = `A user wants to research a topic on YouTube. Turn their intent into up to ${QUERIES} effective YouTube search queries (short, keyword-rich, the way people actually search). Cover slightly different angles if useful. Use the language the topic is most discussed in (usually English for tech).
+
+Intent: "${intent}"
+
+Output ONLY a raw JSON array of strings, no fences, no commentary. Example: ["query one","query two"]`;
+    try {
+        const out = await chat(prompt, { system: 'You output ONLY a raw JSON array of search-query strings.', temperature: 0.4 });
+        const arr = parseJsonArray(out);
+        const qs = (arr ?? []).filter((s) => typeof s === 'string' && s.trim().length > 0).slice(0, QUERIES);
+        return qs.length ? qs : [intent];
+    }
+    catch {
+        return [intent]; // expansion is best-effort; fall back to the raw intent
+    }
+}
+// ---------- stage 3: re-rank candidates against intent (metadata only) ----------
+async function rerank(intent, hits) {
+    if (hits.length === 0)
+        return [];
+    const compact = hits.map(h => ({ id: h.videoId, title: h.title, channel: h.channelTitle, published: h.publishedAt, desc: (h.description || '').slice(0, 280) }));
+    const prompt = `Rank these YouTube videos by how well they serve the user's intent. Judge on title + channel + description only (no transcripts). Drop clearly off-topic, clickbait, or duplicate-angle results.
+
+Intent: "${intent}"
+
+Candidates:
+${JSON.stringify(compact)}
+
+Output ONLY a raw JSON array, best first, no fences:
+[{"id":"VIDEO_ID","keep":true,"score":0-100,"reason":"max 12 words"},...]
+Set keep=false for anything not worth the user's time.`;
+    try {
+        const out = await chat(prompt, { system: 'You output ONLY a raw JSON array as instructed.', temperature: 0 });
+        const arr = parseJsonArray(out);
+        if (!arr)
+            return hits.map(h => ({ ...h })); // fall back: keep all, original order
+        const byId = new Map(hits.map(h => [h.videoId, h]));
+        const ranked = [];
+        for (const r of arr) {
+            if (!r || r.keep === false)
+                continue;
+            const h = byId.get(r.id);
+            if (h)
+                ranked.push({ ...h, score: typeof r.score === 'number' ? r.score : undefined, reason: r.reason });
+        }
+        return ranked.length ? ranked : hits.map(h => ({ ...h }));
+    }
+    catch {
+        return hits.map(h => ({ ...h }));
+    }
+}
+// ---------- mega-summary for one candidate (the triage artifact) ----------
+async function megaSummary(c, transcript, intent) {
+    const prompt = `Summarize this YouTube video in ${LANG} for a user researching: "${intent}". Make it a RICH, standalone summary they can decide on and that will later feed a cross-video comparison — OR return 'OFFTOPIC: <reason>' if the transcript clearly doesn't serve the intent.
+
+Video:
+- title: ${c.title}
+- channel: ${c.channelTitle}
+- published: ${c.publishedAt}
+- url: https://youtube.com/watch?v=${c.videoId}
+
+Transcript:
+${transcript}
+
+If on-topic, write:
+- Header: ### ${c.channelTitle} — "${c.title}"
+- Subtitle: _${c.publishedAt} · https://youtube.com/watch?v=${c.videoId}_
+- One sentence on relevance to the intent
+- 3-6 numbered thematic sections × 2-4 sentences, concrete: which options/tools are discussed, the criteria, the author's verdict and reasoning. Pull out anything directly comparable (names, pros/cons, recommendations).
+- A short "Bottom line for the intent" line
+- At most 5-8 short quotes from the transcript. No timestamps.
+
+Language: natural ${LANG}; foreign words only for proper nouns or established technical terms.
+Output ONLY the summary OR 'OFFTOPIC: <reason>'. No preamble.`;
+    return chat(prompt, {
+        system: `You are a research-grade video summarizer writing in ${LANG}. Output only the summary or 'OFFTOPIC: <reason>'.`,
+        model: getModel(),
+    });
+}
+// ---------- stage 6: comparison across kept summaries ----------
+async function synthesizeComparison(intent, kept) {
+    const corpus = kept.map((k, i) => `--- VIDEO ${i + 1}: ${k.channelTitle} — "${k.title}" (${k.publishedAt})\nhttps://youtube.com/watch?v=${k.videoId}\n${k.summary}`).join('\n\n');
+    const prompt = `The user researched "${intent}" and kept ${kept.length} YouTube video summaries below. Synthesize a single comparison in ${LANG} that actually helps them decide.
+
+${corpus}
+
+Write:
+- One-paragraph bottom line answering the intent directly.
+- A comparison of the concrete options/tools across the videos (a Markdown table when it fits: option · who recommends it · pros · cons · best for).
+- Consensus vs disagreements between the sources.
+- A final recommendation with the reasoning, and who it's for.
+
+Language: natural ${LANG}; foreign words only for proper nouns or established technical terms. Cite videos as [1], [2]… matching the order above. Output only the comparison.`;
+    return chat(prompt, { system: `You synthesize a decision-grade comparison in ${LANG}. No preamble.`, model: getModel() });
+}
+// ---------- lazy yield: advance to the next candidate that has a transcript ----------
+async function yieldNext(queue) {
+    while (queue.cursor < queue.candidates.length) {
+        const c = queue.candidates[queue.cursor];
+        const t = await fetchTranscript(c.videoId);
+        if (t.code === 2)
+            emit({ status: 'rate_limited' }); // blocked IP — stop, don't advance
+        if (t.code !== 0 || !t.stdout.trim()) { // no transcript → auto-skip
+            queue.cursor++;
+            writeJSON(SEARCH_QUEUE_FILE, queue);
+            continue;
+        }
+        const summary = await megaSummary(c, t.stdout, queue.intent);
+        if (summary.startsWith('OFFTOPIC:')) { // re-rank missed it → auto-skip
+            queue.cursor++;
+            writeJSON(SEARCH_QUEUE_FILE, queue);
+            continue;
+        }
+        const pending = { videoId: c.videoId, title: c.title, channelTitle: c.channelTitle, publishedAt: c.publishedAt, summary };
+        writeJSON(SEARCH_PENDING_FILE, pending);
+        emit({
+            status: 'decision_needed',
+            summary,
+            pending: { videoId: c.videoId, title: c.title, channelTitle: c.channelTitle, publishedAt: c.publishedAt, position: queue.cursor + 1, total: queue.candidates.length },
+        });
+    }
+    emit({ status: 'done', kept: loadKept().length });
+}
+// ---------- main ----------
+async function main() {
+    if (!process.env.YT_BRIEFING_YOUTUBE_API_KEY && (RESET || (intentArg && !loadQueue()))) {
+        emit({ status: 'error', error: 'YT_BRIEFING_YOUTUBE_API_KEY is not set — add a YouTube Data API v3 key to .yt-briefing/.env (see README → setup / .env.example).' });
+    }
+    // --compare: synthesize from kept summaries.
+    if (COMPARE) {
+        const queue = loadQueue();
+        const kept = loadKept();
+        if (kept.length === 0)
+            emit({ status: 'done', kept: 0 });
+        const comparison = await synthesizeComparison(queue?.intent ?? '', kept);
+        emit({ status: 'compare', comparison });
+    }
+    // --keep / --skip: record decision on the pending candidate, then advance + yield next.
+    if (KEEP || SKIP) {
+        const queue = loadQueue();
+        if (!queue)
+            emit({ status: 'error', error: 'No active search. Start one: yt-search "<intent>".' });
+        if (KEEP) {
+            const pending = readJSON(SEARCH_PENDING_FILE, null);
+            if (pending) {
+                const kept = loadKept();
+                kept.push(pending);
+                writeJSON(SEARCH_KEPT_FILE, kept);
+            }
+        }
+        queue.cursor++;
+        writeJSON(SEARCH_QUEUE_FILE, queue);
+        await yieldNext(queue);
+    }
+    // Resume an in-progress search (bare call, same intent) without rebuilding.
+    const existing = loadQueue();
+    if (existing && !RESET && (!intentArg || intentArg === existing.intent)) {
+        await yieldNext(existing);
+    }
+    // Fresh search (new intent or --reset).
+    if (!intentArg)
+        emit({ status: 'error', error: 'Provide an intent: yt-search "<what to research>".' });
+    const queries = await expandQueries(intentArg);
+    const seen = new Set();
+    const hits = [];
+    for (const q of queries) {
+        let batch = [];
+        try {
+            batch = await searchVideos(q, { maxResults: 10, since: SINCE });
+        }
+        catch (e) {
+            emit({ status: 'error', error: e.message });
+        }
+        for (const h of batch)
+            if (!seen.has(h.videoId)) {
+                seen.add(h.videoId);
+                hits.push(h);
+            }
+    }
+    if (hits.length === 0)
+        emit({ status: 'no_results' });
+    const ranked = (await rerank(intentArg, hits)).slice(0, MAX);
+    if (ranked.length === 0)
+        emit({ status: 'no_results' });
+    const queue = { built_at: new Date().toISOString(), intent: intentArg, candidates: ranked, cursor: 0 };
+    writeJSON(SEARCH_QUEUE_FILE, queue);
+    writeJSON(SEARCH_KEPT_FILE, []); // fresh search → fresh compare corpus
+    await yieldNext(queue);
+}
+main().catch(err => emit({ status: 'error', error: err.message }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yt-briefing",
-  "version": "0.3.2",
+  "version": "0.5.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": {