yt-briefing 0.5.0 → 0.7.0

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

@@ -1,15 +1,19 @@
 ---
 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.
+description: Search WITHIN one YouTube channel by intent — name a channel and what you're after; the engine lists that channel's uploads, ranks them against your intent (metadata only, no transcript yet), then lazily yields ONE matching video at a time with a rich summary. You keep or skip each; at the end it synthesizes a comparison from everything you kept. Channel-scoped, not whole-YouTube. 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 channel (@handle or URL) and a descriptive intent, e.g. "@t3dotgg which terminal for AI coding". Optional --top N (default 10), --scan N, --since YYYY-MM-DD.
 ---
 
 ## 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.
+`src/yt-search.ts` is the whole engine: list one channel's uploads (cheap — `playlistItems`, ~1 quota unit/page; NOT `search.list`) → re-rank them against your intent on metadata only (title/description, no transcript) → **lazy** one-candidate-at-a-time yield with a rich summary → record keep/skip → on demand synthesize a comparison from everything kept. **Channel-scoped on purpose** — you choose where to look; it does NOT search all of YouTube. Matching is descriptive: the LLM filters the channel's videos by intent. This skill is a thin loop — paste the summary, collect keep/skip, show the final comparison.
 
 **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.
 
+## Inputs
+
+The user gives a **channel** (`@handle` or a channel URL) and an **intent** (what to look for). Pass the channel via `--channel` and the intent as the quoted positional. If the user names a channel but no clear intent (or vice versa), ask for the missing half before running.
+
 ## 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.
@@ -17,11 +21,11 @@ Read `data/config.json` → `output_lang` once at the start. Phrase the question
 ## Loop
 
 ```
-out = JSON.parse(`bun run src/yt-search.ts "<intent from the user>" --reset`)   // first call
+out = JSON.parse(`bun run src/yt-search.ts "<intent>" --channel <@handle|url> --reset`)   // first call
 while true:
   out.status:
     "error"           → show out.error verbatim, stop
-    "no_results"      → tell the user nothing relevant was found, stop
+    "no_results"      → tell the user nothing in that channel matched, 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
@@ -38,16 +42,16 @@ while true:
     - 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.
+  - The script reads the pending candidate from cache; pass only `--keep` / `--skip` / `--compare` (no channel/intent again). 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` → run `out = JSON.parse(\`bun run src/yt-search.ts --compare\`)`; when it returns `status:"compare"`, paste `out.comparison` **verbatim** as your chat text (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`.
+- **Scope:** one channel per search. Listing is cheap; the cost is the lazy transcript fetches, so let the user keep/skip rather than pulling everything. A bare resume (no `--reset`) continues the same ranked queue. `--scan N` (default 50) caps how many recent uploads are considered; `--since` widens by date.
+- **Stateless triage:** independent of `/yt` (no channel profiles, no ratings written). For the recurring multi-channel briefing use `/yt`; for one known video use `/yt-transcribe`.

package/README.md

@@ -77,24 +77,17 @@ The skill is installed alongside `/yt` by `init` / `install-skill`. From the pla
 npx yt-briefing transcribe <url-or-id> --lang auto   # prints the transcript to stdout
 ```
 
-## Research a topic across YouTube
+## Search within a channel
 
-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.
+Mine one channel's videos for a topic and get a comparison. Run `/yt-search` with a channel and
+an intent — e.g. `/yt-search @betterstack which terminal for AI coding`.
 
-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.
+It covers the channel's **whole history** (not just recent uploads), re-ranks every upload against
+your intent, then lazily yields one matching video at a time to keep or skip — and synthesizes a
+comparison from everything you kept.
 
-```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.
+The one flag is `--top N` — how many of the top re-ranked matches to triage (**default 10**). Raise
+it to go deeper, lower it for a quicker pass: `/yt-search @betterstack which terminal --top 20`.
 
 ## Run it
 
@@ -119,6 +112,23 @@ YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
 Want something else? Change those three lines for OpenRouter (`https://openrouter.ai/api/v1`),
 OpenAI (`https://api.openai.com/v1`), or a local Ollama (`http://localhost:11434/v1`).
 
+### Where the keys live
+
+Keys are read from your project's **root `.env`** only — there is no fallback file. Put them there
+(or export them in the shell / CI — an exported var wins). `bun run init` writes them into your
+root `.env`, merging without clobbering any other variables already in it.
+
+These are **required**, and missing one fails fast naming exactly which (no silent defaults):
+
+```ini
+YT_BRIEFING_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+YT_BRIEFING_LLM_API_KEY=<your-key>
+YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
+YT_BRIEFING_YOUTUBE_API_KEY=<your-key>
+```
+
+`YT_BRIEFING_PROXY` and `YT_BRIEFING_DLP_PATH` are optional. Keep `.env` gitignored.
+
 ## Why an API, not the agent's native model
 
 The filtering and the summaries go through a plain OpenAI-compatible API call from the engine,

package/dist/bootstrap.js

@@ -13,10 +13,11 @@
  * Re-running is safe: it warns before overwriting existing data and lets you bail.
  * Everything it writes is plain Markdown / JSON you can also edit by hand afterwards.
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, 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 { DATA_DIR, BASE_DIR, PKG_ROOT, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, ROOT_ENV_PATH, profilePath, } from "./lib/paths.js";
 import { AGENTS, installSkills, projectSkillsRoot, customSkillsRootDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { loadEnv } from "./lib/env.js";
 import { question } from "./lib/prompt.js";
 import { normalizeHandle, slugify, serializeChannels, serializeState, profileBody, baselineStateRow } from "./lib/channels.js";
 const ask = (q, def = '') => {
@@ -29,8 +30,34 @@ const askYN = (q, def = true) => {
         return def;
     return a.startsWith('y');
 };
+// Secrets: if already provided by the environment (root .env or an exported var), offer to keep it
+// without echoing the value back to the terminal. Returns the kept/typed value.
+const askSecret = (q, preset) => {
+    if (preset)
+        return question(`${q} [Enter = keep the value from your environment]:`).trim() || preset;
+    return ask(q);
+};
+// Merge vars into the project root .env without clobbering: only append keys not already present
+// (so a value the user keeps from their existing root .env stays the single source). Skips empties.
+function mergeRootEnv(vars) {
+    const existing = existsSync(ROOT_ENV_PATH) ? readFileSync(ROOT_ENV_PATH, 'utf8') : '';
+    const present = new Set(existing.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('#'))
+        .map(l => l.slice(0, l.indexOf('=')).trim()).filter(Boolean));
+    const additions = vars.filter(([k, v]) => v !== '' && !present.has(k)).map(([k, v]) => `${k}=${v}`);
+    if (additions.length) {
+        const sep = existing && !existing.endsWith('\n') ? '\n' : '';
+        writeFileSync(ROOT_ENV_PATH, existing + sep + additions.join('\n') + '\n', 'utf8');
+    }
+    return additions.map(l => l.slice(0, l.indexOf('=')));
+}
 function main() {
     console.log('\n  yt-briefing — onboarding\n  ' + '─'.repeat(40) + '\n');
+    // See what the environment already provides (root .env / exported vars) so we can offer to keep
+    // those secrets instead of re-asking, and avoid baking a second copy into .yt-briefing/.env.
+    loadEnv();
+    const presetLlmKey = process.env.YT_BRIEFING_LLM_API_KEY ?? '';
+    const presetYtKey = process.env.YT_BRIEFING_YOUTUBE_API_KEY ?? '';
+    const presetProxy = process.env.YT_BRIEFING_PROXY ?? '';
     if (existsSync(CHANNELS_MD)) {
         console.log(`  Existing data found at ${DATA_DIR}`);
         if (!askYN('  Overwrite it?', false)) {
@@ -61,7 +88,7 @@ function main() {
     const picked = PROVIDERS[ask('  Your choice', '1')];
     if (picked) {
         console.log(`\n     → ${picked.name}. Get your key here: ${picked.keyUrl}`);
-        llmKey = ask('  Paste your API key');
+        llmKey = askSecret('  Paste your API key', presetLlmKey);
         llmBaseUrl = picked.base;
         llmModel = ask('  Model (Enter to accept)', picked.model);
     }
@@ -69,13 +96,13 @@ function main() {
         console.log('\n     → Custom / local endpoint (e.g. Ollama at http://localhost:11434/v1)');
         llmBaseUrl = ask('  YT_BRIEFING_LLM_BASE_URL', 'http://localhost:11434/v1');
         llmModel = ask('  YT_BRIEFING_LLM_MODEL', 'llama3.1');
-        llmKey = ask('  YT_BRIEFING_LLM_API_KEY (blank for local)', '');
+        llmKey = askSecret('  YT_BRIEFING_LLM_API_KEY (blank for local)', presetLlmKey);
     }
     console.log('\n  3) YouTube Data API (needed to list channel uploads)');
     console.log('     Get a key: https://console.cloud.google.com → YouTube Data API v3');
-    const ytKey = ask('  YT_BRIEFING_YOUTUBE_API_KEY');
+    const ytKey = askSecret('  YT_BRIEFING_YOUTUBE_API_KEY', presetYtKey);
     console.log('\n  4) Proxy (optional — only needed on datacenter/VPS IPs; see docs/warp-proxy.md)');
-    const ytProxy = ask('  YT_BRIEFING_PROXY (blank = direct)', '');
+    const ytProxy = askSecret('  YT_BRIEFING_PROXY (blank = direct)', presetProxy);
     // 5. Channels ----------------------------------------------------------------
     // Just collect a flat list. No categories, no per-channel rules to define up front —
     // each channel's profile LEARNS what to skip as you rate it (## Skip titles / ## Notes).
@@ -118,21 +145,20 @@ function main() {
     const customDir = AGENTS[agentKey] ? '' : ask('  Skills folder to install into', customSkillsRootDefault());
     // 7. Write everything --------------------------------------------------------
     mkdirSync(CHANNELS_DIR, { recursive: true });
-    // .env
-    const envBody = [
-        `YT_BRIEFING_LLM_BASE_URL=${llmBaseUrl}`,
-        `YT_BRIEFING_LLM_API_KEY=${llmKey}`,
-        `YT_BRIEFING_LLM_MODEL=${llmModel}`,
-        `YT_BRIEFING_YOUTUBE_API_KEY=${ytKey}`,
-        `YT_BRIEFING_PROXY=${ytProxy}`,
-        '',
-    ].join('\n');
-    writeFileSync(ENV_PATH, envBody, 'utf8');
-    // Secret-safety for the consume layout: drop a .gitignore inside .yt-briefing/ so .env never
-    // gets committed regardless of the host project's own ignore rules. data/ stays versionable
-    // (for sync). In a dev clone (BASE_DIR === PKG_ROOT) the repo's own .gitignore already covers it.
+    // Secrets live in the project ROOT .env (the only file the engine reads). Merge into it without
+    // clobbering — keys already there (e.g. kept from the environment) stay the single source. The
+    // engine has no fallback file, so a key not set here (or exported) is a hard error at run time.
+    const envAdded = mergeRootEnv([
+        ['YT_BRIEFING_LLM_BASE_URL', llmBaseUrl],
+        ['YT_BRIEFING_LLM_API_KEY', llmKey],
+        ['YT_BRIEFING_LLM_MODEL', llmModel],
+        ['YT_BRIEFING_YOUTUBE_API_KEY', ytKey],
+        ['YT_BRIEFING_PROXY', ytProxy],
+    ]);
+    // Keep the throwaway cache out of git for the consume layout. data/ stays versionable (for sync).
+    // No secrets live under .yt-briefing/ anymore, so nothing else needs ignoring here.
     if (BASE_DIR !== PKG_ROOT) {
-        writeFileSync(join(BASE_DIR, '.gitignore'), '.env\ndata/.cache/\n', 'utf8');
+        writeFileSync(join(BASE_DIR, '.gitignore'), 'data/.cache/\n', 'utf8');
     }
     // config.json
     writeFileSync(CONFIG_JSON, JSON.stringify({ output_lang: outputLang }, null, 2) + '\n', 'utf8');
@@ -144,7 +170,7 @@ function main() {
         writeFileSync(profilePath(c.slug), profileBody(c.handle, c.slug), 'utf8');
     console.log('  ' + '─'.repeat(40));
     console.log(`  Done. Wrote:`);
-    console.log(`    ${ENV_PATH}`);
+    console.log(`    ${ROOT_ENV_PATH}  ${envAdded.length ? `(+${envAdded.join(', ')})` : '(no new keys — already set)'}`);
     console.log(`    ${CONFIG_JSON}`);
     console.log(`    ${CHANNELS_MD}`);
     console.log(`    ${STATE_MD}`);

package/dist/cli.js

@@ -12,7 +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)
+ *   yt-briefing search "<intent>" --channel <@handle|url>   search within one channel → triage → compare
  */
 import { spawnSync } from 'node:child_process';
 import { script } from "./lib/paths.js";

package/dist/lib/env.js

@@ -0,0 +1,38 @@
+/**
+ * Env loader + required-variable preflight — the one place that reads secrets off disk.
+ *
+ * Keys come from the project's root `.env` ONLY. There is no fallback file: dotenv loads root
+ * `.env` into process.env (anything already exported wins, since dotenv never overrides). Missing
+ * a required variable is a hard error that names exactly which one — never a silent default.
+ *
+ * Call `loadEnv()` once at every entrypoint, then `requireEnv([...])` for what that command needs.
+ */
+import dotenv from 'dotenv';
+import { ROOT_ENV_PATH } from "./paths.js";
+let done = false;
+/** Load the project's root `.env` into process.env. The only file we read. */
+export function loadEnv() {
+    if (done)
+        return;
+    done = true;
+    dotenv.config({ path: ROOT_ENV_PATH });
+}
+/** The required vars per capability — single source of truth for the preflight checks. */
+export const REQUIRED_LLM = ['YT_BRIEFING_LLM_BASE_URL', 'YT_BRIEFING_LLM_API_KEY', 'YT_BRIEFING_LLM_MODEL'];
+export const REQUIRED_YOUTUBE = ['YT_BRIEFING_YOUTUBE_API_KEY'];
+/** Names from `names` that are missing or empty in the environment, in order. */
+export function missingEnv(names) {
+    return names.filter(n => !process.env[n]);
+}
+/** Human-readable error for a set of missing vars — names each one and where to set it. */
+export function missingEnvMessage(missing) {
+    const plural = missing.length > 1;
+    return `Missing required environment variable${plural ? 's' : ''}: ${missing.join(', ')}. ` +
+        `Set ${plural ? 'them' : 'it'} in your project root .env (see README → Providers → Where the keys live).`;
+}
+/** Throw a clear, named error if any required var is missing. */
+export function requireEnv(names) {
+    const missing = missingEnv(names);
+    if (missing.length)
+        throw new Error(missingEnvMessage(missing));
+}

package/dist/lib/llm.js

@@ -10,21 +10,22 @@
  * the default — cheap and fast enough for the batch title filter, capable enough for
  * the summaries.
  *
- * Env (see .env.example):
- *   YT_BRIEFING_LLM_BASE_URL   default https://openrouter.ai/api/v1
+ * Env (see .env.example) — all required, no defaults:
+ *   YT_BRIEFING_LLM_BASE_URL   required (e.g. https://openrouter.ai/api/v1)
  *   YT_BRIEFING_LLM_API_KEY    required
- *   YT_BRIEFING_LLM_MODEL      default google/gemini-2.5-flash
+ *   YT_BRIEFING_LLM_MODEL      required (e.g. google/gemini-2.5-flash)
  */
-const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
-const DEFAULT_MODEL = "google/gemini-2.5-flash";
+import { requireEnv, REQUIRED_LLM } from "./env.js";
 export function getModel() {
-    return process.env.YT_BRIEFING_LLM_MODEL || DEFAULT_MODEL;
+    const model = process.env.YT_BRIEFING_LLM_MODEL;
+    if (!model)
+        throw new Error("Missing required environment variable: YT_BRIEFING_LLM_MODEL. Set it in your project root .env.");
+    return model;
 }
 export async function chat(prompt, opts = {}) {
-    const baseUrl = (process.env.YT_BRIEFING_LLM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    requireEnv(REQUIRED_LLM);
+    const baseUrl = process.env.YT_BRIEFING_LLM_BASE_URL.replace(/\/+$/, "");
     const apiKey = process.env.YT_BRIEFING_LLM_API_KEY;
-    if (!apiKey)
-        throw new Error("YT_BRIEFING_LLM_API_KEY not set (see .env.example)");
     const model = opts.model || getModel();
     const messages = [];
     if (opts.system)

package/dist/lib/paths.js

@@ -33,6 +33,13 @@ export const BASE_DIR = process.env.YT_BRIEFING_BASE_DIR
     : CONSUMED ? join(process.cwd(), '.yt-briefing') : PKG_ROOT;
 process.env.YT_BRIEFING_BASE_DIR = BASE_DIR; // pin for children (their cwd differs)
 export const ENV_PATH = join(BASE_DIR, '.env');
+/**
+ * The project's root `.env` — the conventional, user-owned home for secrets (12-factor). When
+ * consumed, BASE_DIR is `<project>/.yt-briefing`, so the root is its parent; in a dev clone
+ * BASE_DIR === PKG_ROOT, so the root `.env` *is* ENV_PATH (one file, loaded once). Read-only:
+ * the loader never writes here, so it can't clobber the user's other variables. See lib/env.ts.
+ */
+export const ROOT_ENV_PATH = CONSUMED ? join(dirname(BASE_DIR), '.env') : ENV_PATH;
 export const DATA_DIR = process.env.YT_BRIEFING_DATA_DIR
     ? resolve(process.env.YT_BRIEFING_DATA_DIR)
     : join(BASE_DIR, 'data');

package/dist/lib/yt-api.js

@@ -5,14 +5,14 @@
  * cost ~7s to load from a cold FS cache on every fresh process. The Data API is a
  * trivial REST surface, so direct fetch keeps cold-start near the runtime's own startup.
  *
- * Auth: YT_BRIEFING_YOUTUBE_API_KEY — the entrypoint loads it (dotenv.config from ENV_PATH) before
+ * Auth: YT_BRIEFING_YOUTUBE_API_KEY — the entrypoint loads it (loadEnv() in lib/env.ts) before
  * calling; this module only reads process.env at call time.
  */
 const API = 'https://www.googleapis.com/youtube/v3';
 function apiKey() {
     const k = process.env.YT_BRIEFING_YOUTUBE_API_KEY;
     if (!k)
-        throw new Error('YT_BRIEFING_YOUTUBE_API_KEY env var not set (see .env.example)');
+        throw new Error('Missing required environment variable: YT_BRIEFING_YOUTUBE_API_KEY. Set it in your project root .env (see README → Providers → Where the keys live).');
     return k;
 }
 async function get(path, params) {
@@ -58,7 +58,7 @@ async function listUploads(playlistId, since, maxCount) {
                 hitOld = true;
                 break;
             }
-            videos.push({ videoId: item.snippet.resourceId.videoId, title: item.snippet.title, publishedAt });
+            videos.push({ videoId: item.snippet.resourceId.videoId, title: item.snippet.title, publishedAt, description: item.snippet.description ?? '' });
             if (maxCount !== null && videos.length >= maxCount)
                 return videos;
         }
@@ -110,35 +110,6 @@ 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-channel-pending.js

@@ -12,11 +12,11 @@
  * Empty result is valid (channel has no new content).
  */
 import { readFileSync } from 'fs';
-import dotenv from 'dotenv';
+import { loadEnv } from "./lib/env.js";
 import { parseState } from "./lib/yt-lib.js";
-import { STATE_MD, ENV_PATH } from "./lib/paths.js";
+import { STATE_MD } from "./lib/paths.js";
 import { fetchChannelVideos } from "./lib/yt-api.js";
-dotenv.config({ path: ENV_PATH });
+loadEnv();
 const handle = process.argv[2];
 if (!handle) {
     console.error('Usage: yt-channel-pending @HANDLE   (internal helper)');

package/dist/yt-channel-videos.js

@@ -17,10 +17,9 @@
  *
  * Quota: ~1 unit per page (playlistItems.list) + 1 unit per 50 videos (videos.list).
  */
-import dotenv from 'dotenv';
-import { ENV_PATH } from "./lib/paths.js";
+import { loadEnv } from "./lib/env.js";
 import { fetchChannelVideos } from "./lib/yt-api.js";
-dotenv.config({ path: ENV_PATH });
+loadEnv();
 const args = process.argv.slice(2);
 const handleOrId = args[0];
 const sinceIdx = args.indexOf('--since');

package/dist/yt-rating.js

@@ -17,10 +17,10 @@
  * bullets are de-duplicated; a state.md re-bump is a no-op.
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import dotenv from 'dotenv';
+import { loadEnv } from "./lib/env.js";
 import { parseChannels, appendSkipTitle, appendNote, bumpStatePointer } from "./lib/yt-lib.js";
-import { CHANNELS_MD, STATE_MD, PENDING_FILE, ENV_PATH, profilePath } from "./lib/paths.js";
-dotenv.config({ path: ENV_PATH });
+import { CHANNELS_MD, STATE_MD, PENDING_FILE, profilePath } from "./lib/paths.js";
+loadEnv();
 function getArg(args, name) {
     const idx = args.indexOf(name);
     return idx !== -1 && args[idx + 1] !== undefined ? args[idx + 1] : null;

package/dist/yt-search.js

@@ -1,23 +1,22 @@
 #!/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).
+ * yt-search.ts — search WITHIN one channel by intent, then lazy triage → comparison. The third
+ * yt-briefing mode, sibling to the channel briefing (yt-sweep) and one-shot transcribe.
  *
- * 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.
+ * You point it at a channel and describe what you're after ("which terminal does he recommend
+ * for AI coding"); the engine:
+ *   1. lists that channel's uploads (cheap — playlistItems, 1 quota unit/page; NOT search.list),
+ *   2. re-ranks them against your intent on metadata only — title/description, NO transcript yet,
+ *   3. yields ONE matching video at a time with a rich summary, lazily — never a burst of
+ *      transcript fetches (a burst looks like scraping and gets the IP blocked),
+ *   4. records your keep/skip decision; kept summaries accumulate in a cache,
+ *   5. 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).
+ * Channel-scoped on purpose: you choose where to look. Matching is descriptive — the LLM filters
+ * the channel's videos by intent (no exact-keyword needed).
  *
  * 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 "<intent>" --channel <@handle|url> [--reset] [--top N] [--scan 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
@@ -26,39 +25,55 @@
  *   {"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":"no_results"}                 the channel has no videos matching 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.)
+ *   {"status":"error","error":"<msg>"}      setup/config problem (missing key, missing channel, …)
  *
  * 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 { loadEnv, missingEnv, missingEnvMessage, REQUIRED_LLM, REQUIRED_YOUTUBE } from "./lib/env.js";
 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 });
+import { fetchChannelVideos } from "./lib/yt-api.js";
+import { normalizeHandle } from "./lib/channels.js";
+import { PKG_ROOT, CACHE_DIR, SEARCH_QUEUE_FILE, SEARCH_PENDING_FILE, SEARCH_KEPT_FILE, script, } from "./lib/paths.js";
+loadEnv();
 mkdirSync(CACHE_DIR, { recursive: true });
 const RUNTIME = process.execPath;
 const LANG = outputLang();
 const argv = process.argv.slice(2);
+const VALUE_FLAGS = new Set(['--channel', '--top', '--scan', '--since', '--lang']);
 const has = (f) => argv.includes(f);
 const flagVal = (f) => {
     const i = argv.indexOf(f);
-    return i !== -1 && argv[i + 1] ? argv[i + 1] : null;
+    return i !== -1 && argv[i + 1] != null ? 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;
+// First token that is neither a flag nor a flag's value is the intent.
+function positionalIntent() {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            if (VALUE_FLAGS.has(a))
+                i++;
+            continue;
+        }
+        if (i > 0 && VALUE_FLAGS.has(argv[i - 1]))
+            continue;
+        return a;
+    }
+    return null;
+}
+const intentArg = positionalIntent();
 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 CHANNEL = flagVal('--channel');
+const TOP = Math.max(1, parseInt(flagVal('--top') || '10', 10));
+const SCAN = Math.max(1, parseInt(flagVal('--scan') || '50', 10)); // recent uploads to consider when no --since
 const SINCE = flagVal('--since');
 const LANGTRACK = flagVal('--lang') || 'auto';
 function emit(obj) {
@@ -89,7 +104,7 @@ function fetchTranscript(videoId) {
         p.on('error', reject);
     });
 }
-/** Strip ```fences``` and slice the outermost JSON array from an LLM reply. */
+/** Slice the outermost JSON array from an LLM reply (tolerates stray prose / fences). */
 function parseJsonArray(out) {
     const start = out.indexOf('['), end = out.lastIndexOf(']');
     if (start === -1 || end === -1 || end < start)
@@ -101,44 +116,27 @@ function parseJsonArray(out) {
         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)
+/** Re-rank a channel's videos against the intent (metadata only — no transcript). */
+async function rerank(intent, items) {
+    if (items.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.
+    const compact = items.map(h => ({ id: h.videoId, title: h.title, published: h.publishedAt, desc: (h.description || '').slice(0, 280) }));
+    const prompt = `From this YouTube channel's videos, pick the ones that serve the user's intent and rank them. Judge on title + description only (no transcripts). Drop anything off-topic.
 
 Intent: "${intent}"
 
-Candidates:
+Videos:
 ${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.`;
+Set keep=false for anything not relevant to the intent.`;
     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]));
+            return items; // fall back: keep all, original (newest-first) order
+        const byId = new Map(items.map(h => [h.videoId, h]));
         const ranked = [];
         for (const r of arr) {
             if (!r || r.keep === false)
@@ -147,13 +145,13 @@ Set keep=false for anything not worth the user's time.`;
             if (h)
                 ranked.push({ ...h, score: typeof r.score === 'number' ? r.score : undefined, reason: r.reason });
         }
-        return ranked.length ? ranked : hits.map(h => ({ ...h }));
+        return ranked.length ? ranked : items;
     }
     catch {
-        return hits.map(h => ({ ...h }));
+        return items;
     }
 }
-// ---------- mega-summary for one candidate (the triage artifact) ----------
+/** Rich, standalone summary for one candidate — the triage artifact + compare input. */
 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.
 
@@ -181,7 +179,7 @@ Output ONLY the summary OR 'OFFTOPIC: <reason>'. No preamble.`;
         model: getModel(),
     });
 }
-// ---------- stage 6: comparison across kept summaries ----------
+/** Synthesize a comparison across everything kept. */
 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.
@@ -197,7 +195,7 @@ Write:
 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 ----------
+/** Lazy yield: advance to the next candidate that has a transcript, summarize, emit. */
 async function yieldNext(queue) {
     while (queue.cursor < queue.candidates.length) {
         const c = queue.candidates[queue.cursor];
@@ -225,10 +223,14 @@ async function yieldNext(queue) {
     }
     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).' });
+    // LLM is needed on every path (rerank, summaries, compare). Fail fast naming any missing var
+    // (the throw is turned into a status:"error" by the .catch below). YouTube is checked separately,
+    // only when building a fresh queue (the compare/keep/skip paths work off cache, no API).
+    {
+        const missing = missingEnv(REQUIRED_LLM);
+        if (missing.length)
+            emit({ status: 'error', error: missingEnvMessage(missing) });
     }
     // --compare: synthesize from kept summaries.
     if (COMPARE) {
@@ -243,7 +245,7 @@ async function main() {
     if (KEEP || SKIP) {
         const queue = loadQueue();
         if (!queue)
-            emit({ status: 'error', error: 'No active search. Start one: yt-search "<intent>".' });
+            emit({ status: 'error', error: 'No active search. Start one: yt-search "<intent>" --channel <@handle>.' });
         if (KEEP) {
             const pending = readJSON(SEARCH_PENDING_FILE, null);
             if (pending) {
@@ -256,37 +258,38 @@ async function main() {
         writeJSON(SEARCH_QUEUE_FILE, queue);
         await yieldNext(queue);
     }
-    // Resume an in-progress search (bare call, same intent) without rebuilding.
+    // Resume an in-progress search (bare call, same intent + channel) without rebuilding.
     const existing = loadQueue();
-    if (existing && !RESET && (!intentArg || intentArg === existing.intent)) {
+    if (existing && !RESET && (!intentArg || intentArg === existing.intent) && (!CHANNEL || normalizeHandle(CHANNEL) === existing.channel)) {
         await yieldNext(existing);
     }
-    // Fresh search (new intent or --reset).
+    // Fresh search: needs an intent AND a channel AND the YouTube key (to list the channel).
+    {
+        const missing = missingEnv(REQUIRED_YOUTUBE);
+        if (missing.length)
+            emit({ status: 'error', error: missingEnvMessage(missing) });
+    }
     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);
-            }
+        emit({ status: 'error', error: 'Provide an intent: yt-search "<what to look for>" --channel <@handle|url>.' });
+    if (!CHANNEL)
+        emit({ status: 'error', error: 'Provide a channel: --channel <@handle|url>. /yt-search searches within one channel, not all of YouTube.' });
+    const handle = normalizeHandle(CHANNEL);
+    if (!handle)
+        emit({ status: 'error', error: `Could not read a channel handle from "${CHANNEL}" — use @name or the channel URL.` });
+    let videos;
+    try {
+        videos = await fetchChannelVideos(handle, { since: SINCE, limit: SINCE ? null : SCAN, enrich: false });
+    }
+    catch (e) {
+        emit({ status: 'error', error: e.message });
     }
-    if (hits.length === 0)
+    if (videos.length === 0)
         emit({ status: 'no_results' });
-    const ranked = (await rerank(intentArg, hits)).slice(0, MAX);
+    const pool = videos.map(v => ({ videoId: v.videoId, title: v.title, channelTitle: handle, publishedAt: v.publishedAt, description: v.description }));
+    const ranked = (await rerank(intentArg, pool)).slice(0, TOP);
     if (ranked.length === 0)
         emit({ status: 'no_results' });
-    const queue = { built_at: new Date().toISOString(), intent: intentArg, candidates: ranked, cursor: 0 };
+    const queue = { built_at: new Date().toISOString(), intent: intentArg, channel: handle, candidates: ranked, cursor: 0 };
     writeJSON(SEARCH_QUEUE_FILE, queue);
     writeJSON(SEARCH_KEPT_FILE, []); // fresh search → fresh compare corpus
     await yieldNext(queue);

package/dist/yt-sweep.js

@@ -49,12 +49,12 @@
  */
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, renameSync, appendFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import dotenv from 'dotenv';
+import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_LLM, REQUIRED_YOUTUBE } from "./lib/env.js";
 import { parseChannels, parseState, bumpStatePointer } from "./lib/yt-lib.js";
 import { chat, getModel } from "./lib/llm.js";
 import { outputLang } from "./lib/config.js";
-import { PKG_ROOT, ENV_PATH, CHANNELS_MD, STATE_MD, CACHE_DIR, QUEUE_FILE, REST_FILE, PENDING_FILE, PREFETCH_FILE, LOG_FILE, profilePath, script, } from "./lib/paths.js";
-dotenv.config({ path: ENV_PATH });
+import { PKG_ROOT, CHANNELS_MD, STATE_MD, CACHE_DIR, QUEUE_FILE, REST_FILE, PENDING_FILE, PREFETCH_FILE, LOG_FILE, profilePath, script, } from "./lib/paths.js";
+loadEnv();
 mkdirSync(CACHE_DIR, { recursive: true });
 // Re-invoke sibling scripts with the SAME runtime that launched us (bun/node/deno),
 // never a hardcoded binary — the tool must run wherever the user installed it.
@@ -542,12 +542,14 @@ if (reset) {
     clearRest();
     clearPrefetch();
 }
-// Fatal config check, foreground only (the detached --fill / --prefetch children already
-// exited above). A missing YouTube Data API key makes EVERY channel expansion throw the same
-// error, which the per-channel `catch` collapses to 0 items — surfacing as a misleading
-// `status:"done"` ("no new videos"). Fail fast with a clear, actionable error instead.
-if (!process.env.YT_BRIEFING_YOUTUBE_API_KEY) {
-    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 → first run / .env.example).' });
+// Fatal config preflight, foreground only (the detached --fill / --prefetch children already
+// exited above). A missing key would otherwise surface as a misleading `status:"done"` ("no new
+// videos") — the YouTube error is collapsed by the per-channel catch, and a missing LLM key is
+// swallowed by the title-filter's keep-all fallback. Fail fast naming every missing var instead.
+{
+    const missing = missingEnv([...REQUIRED_LLM, ...REQUIRED_YOUTUBE]);
+    if (missing.length)
+        emit({ status: 'error', error: missingEnvMessage(missing) });
 }
 const queue = loadQueue() ?? buildQueue();
 await advance(queue);

package/dist/yt-transcript.js

@@ -25,11 +25,11 @@ import { spawnSync } from 'node:child_process';
 import { mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import dotenv from 'dotenv';
-import { CACHE_DIR, ENV_PATH } from "./lib/paths.js";
+import { loadEnv } from "./lib/env.js";
+import { CACHE_DIR } from "./lib/paths.js";
 // Load .env so YT_BRIEFING_PROXY is set when run standalone under Node (Bun auto-loads it; Node doesn't).
 // When spawned by yt-sweep, the parent already loaded it and the child inherits the env.
-dotenv.config({ path: ENV_PATH });
+loadEnv();
 /** Resolve the yt-dlp binary: explicit env → project-local ./bin → PATH (Windows-aware). */
 function resolveYtDlp() {
     if (process.env.YT_BRIEFING_DLP_PATH)

package/package.json

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