yt-briefing 0.6.0 → 0.8.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

@@ -1,11 +1,11 @@
 # yt-briefing
 
-Save hours on YouTube. yt-briefing watches the channels you follow so you don't have to. It
-turns each new video into a short summary in your own language that keeps what matters and
-skips the filler. Reading it takes a fraction of the time the video would, so you stay on top
-of everything and only watch what's actually worth it.
+Save hours on YouTube. yt-briefing watches the channels you follow so you don't have to. For
+each new video it distills the essence in your own language — every point that matters, with
+only the filler cut, so nothing important is lost. Reading it takes a fraction of the time the
+video would, so you stay on top of everything and only watch what's actually worth it.
 
-It also gets better the more you use it. You give each summary a quick rating, worth my time
+It also gets better the more you use it. You give each briefing a quick rating, worth my time
 or not, and from that it learns what to keep showing you and what to drop. Over time the queue
 becomes yours: less noise, more of what you care about.
 
@@ -46,13 +46,26 @@ yarn add yt-briefing
 bun  add yt-briefing
 ```
 
-3. Onboard:
+3. Put your keys in a `.env` at your project root — all four are required:
+
+```ini
+YT_BRIEFING_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+YT_BRIEFING_LLM_API_KEY=<key>        # free at https://aistudio.google.com/apikey
+YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
+YT_BRIEFING_YOUTUBE_API_KEY=<key>    # console.cloud.google.com → enable "YouTube Data API v3"
+```
+
+Any OpenAI-compatible endpoint works — see [Providers](#providers) to use OpenRouter, OpenAI, or a
+local Ollama instead of Gemini. Miss a key and the engine tells you exactly which one. Keep `.env`
+gitignored; `YT_BRIEFING_PROXY` (datacenter/VPS IPs) is the only optional extra.
+
+4. Onboard:
 
 ```bash
 npx yt-briefing init      # or: bunx yt-briefing init
 ```
 
-`init` asks for your language, your keys, the channels to follow, and which tool runs `/yt`.
+`init` asks for your language, the channels to follow, and which tool runs `/yt`.
 
 Add or remove channels anytime:
 
@@ -79,24 +92,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.
-
-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.
+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`.
 
-```bash
-yt-briefing search "<intent>" --channel <@handle|url> [--max N] [--scan N] [--since YYYY-MM-DD]
-```
+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.
 
-> 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
 
@@ -119,7 +123,8 @@ YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
 > or switch to a paid key (enable billing, same model) to avoid it.
 
 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`).
+OpenAI (`https://api.openai.com/v1`), or a local Ollama (`http://localhost:11434/v1`). Set
+`YT_BRIEFING_LLM_BASE_URL`, `_API_KEY`, and `_MODEL` in your root `.env` (see [Setup](#setup)).
 
 ## Why an API, not the agent's native model
 

package/dist/bootstrap.js

@@ -6,16 +6,17 @@
  *
  * Asks for, and writes:
  *   1. Output language for summaries + ratings   → DATA_DIR/config.json
- *   2. LLM provider / model / key, YouTube key, optional proxy → .env
- *   3. The channels you follow — just a flat list of handles
+ *   2. The channels you follow — just a flat list of handles
  *      → DATA_DIR/channels.md, DATA_DIR/state.md, DATA_DIR/channels/<slug>.md
+ *   3. Which agent runs /yt — installs the skill into its skills dir
  *
- * Re-running is safe: it warns before overwriting existing data and lets you bail.
+ * It does NOT touch keys: those live in your project root .env (see README → Setup); the engine
+ * reads them at run time. Re-running is safe: it warns before overwriting existing data and bails.
  * Everything it writes is plain Markdown / JSON you can also edit by hand afterwards.
  */
 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 { DATA_DIR, BASE_DIR, PKG_ROOT, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, profilePath, } from "./lib/paths.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";
@@ -39,47 +40,15 @@ function main() {
         }
         console.log('');
     }
+    // Keys are NOT asked here — they live in your project root .env (LLM + YouTube; see README
+    // → Setup). The engine reads them at run time and fails fast naming any that are missing.
     // 1. Language ----------------------------------------------------------------
     console.log('  1) Language');
     const outputLang = ask('  Output language for summaries and ratings', 'English');
-    // 2. LLM provider (.env) -----------------------------------------------------
-    // Pick a provider → we prefill its endpoint + a sensible model and ask ONLY for the
-    // key (with the exact link to get it). The recommended free path is the default, so
-    // pressing Enter lands on it — no long URL to paste, nothing to guess.
-    console.log('\n  2) Which AI writes the filtering + summaries? Pick a provider:\n');
-    console.log('     1) Gemini      — FREE key, best way to start   ·  https://aistudio.google.com/apikey');
-    console.log('     2) OpenRouter  — one key for Gemini + GPT + …   ·  https://openrouter.ai/keys');
-    console.log('     3) OpenAI      — GPT models                     ·  https://platform.openai.com/api-keys');
-    console.log('     4) Other / local (Ollama or any custom endpoint)\n');
-    console.log('     Type 1, 2, 3 or 4 and press Enter.  (Just press Enter for 1 — Gemini, recommended.)');
-    const PROVIDERS = {
-        '1': { name: 'Gemini', base: 'https://generativelanguage.googleapis.com/v1beta/openai', model: 'gemini-2.5-flash', keyUrl: 'https://aistudio.google.com/apikey' },
-        '2': { name: 'OpenRouter', base: 'https://openrouter.ai/api/v1', model: 'google/gemini-2.5-flash', keyUrl: 'https://openrouter.ai/keys' },
-        '3': { name: 'OpenAI', base: 'https://api.openai.com/v1', model: 'gpt-4o-mini', keyUrl: 'https://platform.openai.com/api-keys' },
-    };
-    let llmBaseUrl, llmModel, llmKey;
-    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');
-        llmBaseUrl = picked.base;
-        llmModel = ask('  Model (Enter to accept)', picked.model);
-    }
-    else {
-        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)', '');
-    }
-    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');
-    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)', '');
-    // 5. Channels ----------------------------------------------------------------
+    // 2. 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).
-    console.log('\n  5) Channels you follow');
+    console.log('\n  2) Channels you follow');
     console.log('     Add one per line — paste whichever form you have, all work as-is:');
     console.log('     eg. @betterstack, betterstack or https://www.youtube.com/@betterstack');
     console.log('     (Paste the full URL directly — it reads the @handle for you) Empty line to finish.');
@@ -105,34 +74,22 @@ function main() {
     if (channels.length === 0) {
         console.log('\n  No channels added — you can add them later by editing data/channels.md.\n');
     }
-    // 6. Coding agent ------------------------------------------------------------
+    // 3. 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).
     // 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('\n  3) 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('  Skills folder to install into', customSkillsRootDefault());
-    // 7. Write everything --------------------------------------------------------
+    // 4. 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.
+    // Keep the throwaway cache out of git for the consume layout. data/ stays versionable (for sync).
     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 +101,6 @@ 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(`    ${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.8.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": {