yt-briefing 0.6.0 → 0.7.0

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

@@ -1,7 +1,7 @@
 ---
 name: yt-search
 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 --max N, --scan N, --since YYYY-MM-DD.
+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

package/README.md

@@ -79,24 +79,15 @@ npx yt-briefing transcribe <url-or-id> --lang auto   # prints the transcript to
 
 ## Search within a channel
 
-Following a creator and want to mine *their* videos for something specific — and get an actual
-comparison, not a pile of links? Run `/yt-search`, name a **channel** and your **intent**, e.g.
-`@t3dotgg which terminal for AI coding`. It lists that channel's uploads, ranks them against your
-intent (titles/descriptions — no transcripts yet, matching is **descriptive, not exact keywords**),
-then hands you **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.
+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 channel-scoped on purpose (you choose where to look) and lazy — 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>" --channel <@handle|url> [--max N] [--scan N] [--since YYYY-MM-DD]
-```
-
-> Listing a channel's uploads is cheap (`playlistItems`, ~1 quota unit per 50 videos — not the
-> 100-unit `search.list`). `--scan` (default 50) caps how many recent uploads are considered;
-> `--since` widens by date.
+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
 
@@ -121,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/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) {

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

@@ -16,7 +16,7 @@
  * the channel's videos by intent (no exact-keyword needed).
  *
  * Usage (the skill / CLI drives these; one JSON line per call):
- *   yt-search "<intent>" --channel <@handle|url> [--reset] [--max N] [--scan 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
@@ -34,18 +34,18 @@
  */
 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 { fetchChannelVideos } from "./lib/yt-api.js";
 import { normalizeHandle } from "./lib/channels.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 { 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', '--max', '--scan', '--since', '--lang']);
+const VALUE_FLAGS = new Set(['--channel', '--top', '--scan', '--since', '--lang']);
 const has = (f) => argv.includes(f);
 const flagVal = (f) => {
     const i = argv.indexOf(f);
@@ -72,7 +72,7 @@ const KEEP = has('--keep');
 const SKIP = has('--skip');
 const COMPARE = has('--compare');
 const CHANNEL = flagVal('--channel');
-const MAX = Math.max(1, parseInt(flagVal('--max') || '8', 10));
+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';
@@ -224,6 +224,14 @@ async function yieldNext(queue) {
     emit({ status: 'done', kept: loadKept().length });
 }
 async function main() {
+    // 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) {
         const queue = loadQueue();
@@ -255,9 +263,11 @@ async function main() {
     if (existing && !RESET && (!intentArg || intentArg === existing.intent) && (!CHANNEL || normalizeHandle(CHANNEL) === existing.channel)) {
         await yieldNext(existing);
     }
-    // Fresh search: needs an intent AND a channel.
-    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 → setup / .env.example).' });
+    // 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 look for>" --channel <@handle|url>.' });
@@ -276,7 +286,7 @@ async function main() {
     if (videos.length === 0)
         emit({ status: 'no_results' });
     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, MAX);
+    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, channel: handle, candidates: ranked, cursor: 0 };

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.6.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": {