yt-briefing 0.1.0 → 0.2.0

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

@@ -9,7 +9,7 @@ description: Briefing from the YouTube channels you follow — the engine sweeps
 
 `data/state.md` is the only persistent cursor. Session state — queue, pending, prefetch, background fill — lives in `data/.cache/` (rebuilt each run, never important to keep). Internals — lazy queue build, filters, summary format, LLM model, transcript fetching, prefetch, proxy — are in `README.md`, not here. No manual pre-flight: the engine self-invalidates a stale queue (new day or `--reset`).
 
-**Run the engine bare — no redirects.** Its stdout is a pure JSON line and stderr is empty, so `JSON.parse` of the raw output just works; **never** redirect stderr to `/tmp` or any OS temp dir. For timing diagnostics ("why is the sweep slow") run it once with `YT_DEBUG=1` — it appends per-stage timings to the gitignored `data/.cache/sweep.log`.
+**Run the engine bare — no redirects.** Its stdout is a pure JSON line and stderr is empty, so `JSON.parse` of the raw output just works; **never** redirect stderr to `/tmp` or any OS temp dir. For timing diagnostics ("why is the sweep slow") run it once with `YT_BRIEFING_DEBUG=1` — it appends per-stage timings to the gitignored `data/.cache/sweep.log`.
 
 For fast first paint, the engine expands channels in parallel waves until it has the first ratable video, while a detached background process expands the rest in parallel. And while the user rates a video, it warms the **next** video's summary in another background process, so the following step usually emits instantly. All fully internal — the loop below is unchanged.
 

package/README.md

@@ -9,6 +9,16 @@ It also gets better the more you use it. You give each summary a quick rating, w
 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.
 
+## First run vs later
+
+On a channel's first sweep there is no history, so yt-briefing takes the latest video of each
+kind: the newest long-form, the newest short, and the newest live. That gives you a baseline
+without pulling the whole back catalog.
+
+After that it works from history. Each rating moves a per-type cursor forward, so later runs
+only surface videos newer than the ones you already handled, and a session just continues where
+the last one left off.
+
 ## Setup
 
 You'll need Node 18+ or Bun, a YouTube Data API v3 key, an LLM key (a
@@ -55,9 +65,9 @@ Any OpenAI-compatible endpoint works. Gemini 2.5 Flash is the easy default. It's
 and free to start at [Google AI Studio](https://aistudio.google.com/apikey):
 
 ```ini
-LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
-LLM_API_KEY=<gemini-key>
-LLM_MODEL=gemini-2.5-flash
+YT_BRIEFING_LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+YT_BRIEFING_LLM_API_KEY=<gemini-key>
+YT_BRIEFING_LLM_MODEL=gemini-2.5-flash
 ```
 
 > On the free tier Gemini sometimes returns a "model is overloaded / high demand" error. Retry,
@@ -92,7 +102,7 @@ flowing.
 
 ## Sync across machines
 
-Your state is plain files in `.yt-briefing/data/`. Version that folder (or point `YT_DATA_DIR`
+Your state is plain files in `.yt-briefing/data/`. Version that folder (or point `YT_BRIEFING_DATA_DIR`
 at a separate private repo) and commit after each rating. Recipe:
 [docs/sync-across-machines.md](./docs/sync-across-machines.md).
 

package/dist/bootstrap.js

@@ -14,7 +14,8 @@
  * Everything it writes is plain Markdown / JSON you can also edit by hand afterwards.
  */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { DATA_DIR, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, ENV_PATH, profilePath, } from "./lib/paths.js";
+import { join } from 'node:path';
+import { DATA_DIR, BASE_DIR, PKG_ROOT, CHANNELS_DIR, CHANNELS_MD, STATE_MD, CONFIG_JSON, ENV_PATH, profilePath, } from "./lib/paths.js";
 import { AGENTS, installSkill, projectSkillDir, customSkillDirDefault, isPackageDevCwd } from "./lib/skill-install.js";
 import { question } from "./lib/prompt.js";
 const ask = (q, def = '') => {
@@ -94,15 +95,15 @@ function main() {
     }
     else {
         console.log('\n     → Custom / local endpoint (e.g. Ollama at http://localhost:11434/v1)');
-        llmBaseUrl = ask('  LLM_BASE_URL', 'http://localhost:11434/v1');
-        llmModel = ask('  LLM_MODEL', 'llama3.1');
-        llmKey = ask('  LLM_API_KEY (blank for local)', '');
+        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('  YOUTUBE_API_KEY');
+    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_PROXY (blank = direct)', '');
+    const ytProxy = ask('  YT_BRIEFING_PROXY (blank = direct)', '');
     // 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).
@@ -146,14 +147,20 @@ function main() {
     mkdirSync(CHANNELS_DIR, { recursive: true });
     // .env
     const envBody = [
-        `LLM_BASE_URL=${llmBaseUrl}`,
-        `LLM_API_KEY=${llmKey}`,
-        `LLM_MODEL=${llmModel}`,
-        `YOUTUBE_API_KEY=${ytKey}`,
-        `YT_PROXY=${ytProxy}`,
+        `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.
+    if (BASE_DIR !== PKG_ROOT) {
+        writeFileSync(join(BASE_DIR, '.gitignore'), '.env\ndata/.cache/\n', 'utf8');
+    }
     // config.json
     writeFileSync(CONFIG_JSON, JSON.stringify({ output_lang: outputLang }, null, 2) + '\n', 'utf8');
     // channels.md — a flat list of the channels you follow.

package/dist/lib/llm.js

@@ -1,7 +1,7 @@
 /**
  * Minimal OpenAI-compatible chat client — the only LLM dependency in yt-briefing.
  *
- * Provider-agnostic: point LLM_BASE_URL at any OpenAI-compatible endpoint —
+ * Provider-agnostic: point YT_BRIEFING_LLM_BASE_URL at any OpenAI-compatible endpoint —
  * OpenRouter (default, "any model, one key"), Google Gemini's OpenAI-compat
  * endpoint, OpenAI itself, a local Ollama, etc. The tool depends only on an API key
  * here — not on any specific vendor and not on a coding agent being installed.
@@ -11,20 +11,20 @@
  * the summaries.
  *
  * Env (see .env.example):
- *   LLM_BASE_URL   default https://openrouter.ai/api/v1
- *   LLM_API_KEY    required
- *   LLM_MODEL      default google/gemini-2.5-flash
+ *   YT_BRIEFING_LLM_BASE_URL   default https://openrouter.ai/api/v1
+ *   YT_BRIEFING_LLM_API_KEY    required
+ *   YT_BRIEFING_LLM_MODEL      default google/gemini-2.5-flash
  */
 const DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
 const DEFAULT_MODEL = "google/gemini-2.5-flash";
 export function getModel() {
-    return process.env.LLM_MODEL || DEFAULT_MODEL;
+    return process.env.YT_BRIEFING_LLM_MODEL || DEFAULT_MODEL;
 }
 export async function chat(prompt, opts = {}) {
-    const baseUrl = (process.env.LLM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
-    const apiKey = process.env.LLM_API_KEY;
+    const baseUrl = (process.env.YT_BRIEFING_LLM_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const apiKey = process.env.YT_BRIEFING_LLM_API_KEY;
     if (!apiKey)
-        throw new Error("LLM_API_KEY not set (see .env.example)");
+        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

@@ -7,9 +7,9 @@
  *              itself) this IS the package root, so the repo layout (`.env`, `data/`) is
  *              unchanged. When the package is *consumed as a dependency* — PKG_ROOT sits
  *              inside node_modules — that would be wiped on reinstall, so BASE_DIR moves to
- *              `<your project>/.yt-briefing/` instead. Override explicitly with YT_BASE_DIR.
+ *              `<your project>/.yt-briefing/` instead. Override explicitly with YT_BRIEFING_BASE_DIR.
  *   DATA_DIR   the mutable state (subscriptions, profiles, cursor, throwaway cache).
- *              Defaults to <BASE_DIR>/data; override with YT_DATA_DIR to keep it anywhere
+ *              Defaults to <BASE_DIR>/data; override with YT_BRIEFING_DATA_DIR to keep it anywhere
  *              (e.g. a synced git folder, separate from secrets).
  *
  * BASE_DIR and DATA_DIR are pinned back into the environment so detached child processes —
@@ -28,15 +28,15 @@ export const PKG_ROOT = resolve(HERE, '../..'); // package root
 const SCRIPT_EXT = extname(SELF) || '.ts';
 // Consumed as a dependency? Then PKG_ROOT lives under node_modules and must not hold user state.
 const CONSUMED = PKG_ROOT.split(sep).includes('node_modules');
-export const BASE_DIR = process.env.YT_BASE_DIR
-    ? resolve(process.env.YT_BASE_DIR)
+export const BASE_DIR = process.env.YT_BRIEFING_BASE_DIR
+    ? resolve(process.env.YT_BRIEFING_BASE_DIR)
     : CONSUMED ? join(process.cwd(), '.yt-briefing') : PKG_ROOT;
-process.env.YT_BASE_DIR = BASE_DIR; // pin for children (their cwd differs)
+process.env.YT_BRIEFING_BASE_DIR = BASE_DIR; // pin for children (their cwd differs)
 export const ENV_PATH = join(BASE_DIR, '.env');
-export const DATA_DIR = process.env.YT_DATA_DIR
-    ? resolve(process.env.YT_DATA_DIR)
+export const DATA_DIR = process.env.YT_BRIEFING_DATA_DIR
+    ? resolve(process.env.YT_BRIEFING_DATA_DIR)
     : join(BASE_DIR, 'data');
-process.env.YT_DATA_DIR = DATA_DIR; // pin for children (their cwd differs)
+process.env.YT_BRIEFING_DATA_DIR = DATA_DIR; // pin for children (their cwd differs)
 export const CHANNELS_MD = join(DATA_DIR, 'channels.md');
 export const STATE_MD = join(DATA_DIR, 'state.md');
 export const CONFIG_JSON = join(DATA_DIR, 'config.json');

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: YOUTUBE_API_KEY — the entrypoint loads it (dotenv.config from ENV_PATH) before
+ * Auth: YT_BRIEFING_YOUTUBE_API_KEY — the entrypoint loads it (dotenv.config from ENV_PATH) 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.YOUTUBE_API_KEY;
+    const k = process.env.YT_BRIEFING_YOUTUBE_API_KEY;
     if (!k)
-        throw new Error('YOUTUBE_API_KEY env var not set (see .env.example)');
+        throw new Error('YT_BRIEFING_YOUTUBE_API_KEY env var not set (see .env.example)');
     return k;
 }
 async function get(path, params) {

package/dist/yt-channel-videos.js

@@ -13,7 +13,7 @@
  *   Filtered OUT: current and upcoming live broadcasts (no transcript yet, never consumable).
  *   --no-enrich → skip the videos.list pass; type/durationSeconds omitted; no filtering.
  *
- * Requires: YOUTUBE_API_KEY (see .env.example). Thin CLI wrapper over lib/yt-api.ts.
+ * Requires: YT_BRIEFING_YOUTUBE_API_KEY (see .env.example). Thin CLI wrapper over lib/yt-api.ts.
  *
  * Quota: ~1 unit per page (playlistItems.list) + 1 unit per 50 videos (videos.list).
  */

package/dist/yt-sweep.js

@@ -17,7 +17,7 @@
  *   {"status":"rate_limited"}
  *
  * The engine ONLY writes files under DATA_DIR — it never runs git or any VCS. If you
- * want your briefing state versioned, commit DATA_DIR yourself (or point YT_DATA_DIR at
+ * want your briefing state versioned, commit DATA_DIR yourself (or point YT_BRIEFING_DATA_DIR at
  * a synced folder). Keeping persistence out of the engine is deliberate: it stays a pure
  * data tool with zero host coupling.
  *
@@ -71,9 +71,9 @@ const prefetchTarget = pfIdx !== -1 ? argv[pfIdx + 1] : null;
 const today = new Date().toISOString().slice(0, 10);
 const LANG = outputLang();
 // Diagnostics sink. Default: silent (stdout stays a pure JSON line — the caller never
-// has to redirect anything, so no /tmp). With YT_DEBUG set, timing + child stderr append
+// has to redirect anything, so no /tmp). With YT_BRIEFING_DEBUG set, timing + child stderr append
 // to <DATA_DIR>/.cache/sweep.log (gitignored) — never an OS temp dir.
-const DEBUG = !!process.env.YT_DEBUG;
+const DEBUG = !!process.env.YT_BRIEFING_DEBUG;
 const T0 = Date.now();
 const log = (msg) => { if (DEBUG)
     appendFileSync(LOG_FILE, `⏱ ${msg} (+${Date.now() - T0}ms)\n`); };
@@ -85,7 +85,7 @@ function run(cmd) {
         let stdout = '';
         p.stdout.on('data', d => { stdout += d.toString(); });
         // Child stderr → the gitignored debug log only (never parent stderr / stdout), so a
-        // bare invocation emits nothing but the JSON line. Silent unless YT_DEBUG.
+        // bare invocation emits nothing but the JSON line. Silent unless YT_BRIEFING_DEBUG.
         if (DEBUG)
             p.stderr.on('data', d => appendFileSync(LOG_FILE, d.toString()));
         else

package/dist/yt-transcript.js

@@ -12,13 +12,13 @@
  * Uses yt-dlp for subtitle extraction (handles all YouTube caption formats).
  *
  * yt-dlp lookup (so a project-local install needs no global PATH pollution):
- *   1. $YT_DLP_PATH if set
+ *   1. $YT_BRIEFING_DLP_PATH if set
  *   2. <package>/bin/yt-dlp  (yt-dlp.exe on Windows) if present
  *   3. `yt-dlp` on PATH       (yt-dlp.exe on Windows)
  * See README.md → Requirements for per-OS install methods.
  *
- * YT_PROXY env (optional): HTTP proxy URL — required on datacenter/VPS IPs which
- *   YouTube blocks. Example: YT_PROXY=http://127.0.0.1:1080 (Cloudflare WARP via
+ * YT_BRIEFING_PROXY env (optional): HTTP proxy URL — required on datacenter/VPS IPs which
+ *   YouTube blocks. Example: YT_BRIEFING_PROXY=http://127.0.0.1:1080 (Cloudflare WARP via
  *   Docker). See docs/warp-proxy.md.
  */
 import { spawnSync } from 'node:child_process';
@@ -27,13 +27,13 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import dotenv from 'dotenv';
 import { CACHE_DIR, ENV_PATH } from "./lib/paths.js";
-// Load .env so YT_PROXY is set when run standalone under Node (Bun auto-loads it; Node doesn't).
+// 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 });
 /** Resolve the yt-dlp binary: explicit env → project-local ./bin → PATH (Windows-aware). */
 function resolveYtDlp() {
-    if (process.env.YT_DLP_PATH)
-        return process.env.YT_DLP_PATH;
+    if (process.env.YT_BRIEFING_DLP_PATH)
+        return process.env.YT_BRIEFING_DLP_PATH;
     const exe = process.platform === 'win32' ? 'yt-dlp.exe' : 'yt-dlp';
     const local = join(dirname(fileURLToPath(import.meta.url)), '..', 'bin', exe);
     return existsSync(local) ? local : exe; // bare name → looked up on PATH
@@ -61,7 +61,7 @@ function extractVideoId(input) {
     process.exit(3);
 }
 const videoId = extractVideoId(rawInput);
-const proxyUrl = process.env.YT_PROXY;
+const proxyUrl = process.env.YT_BRIEFING_PROXY;
 function vttToText(vtt) {
     let prev = '';
     const parts = [];
@@ -106,7 +106,7 @@ catch { } };
 if (result.error) {
     cleanup();
     const msg = result.error.code === 'ENOENT'
-        ? `yt-dlp not found (looked for "${YT_DLP}") — install it or set YT_DLP_PATH (see README.md → Requirements)`
+        ? `yt-dlp not found (looked for "${YT_DLP}") — install it or set YT_BRIEFING_DLP_PATH (see README.md → Requirements)`
         : `yt-dlp spawn error: ${result.error.message}`;
     console.error(msg);
     process.exit(3);

package/docs/sync-across-machines.md

@@ -23,11 +23,11 @@ your project's own git: push from machine A, pull on machine B. Keep `.yt-briefi
 git-ignored — secrets stay per machine.
 
 Want briefing state in **its own** repo instead (e.g. a laptop and a headless VPS that share
-nothing else)? Point `YT_DATA_DIR` at a folder you control and version that:
+nothing else)? Point `YT_BRIEFING_DATA_DIR` at a folder you control and version that:
 
 ```bash
 # .env  (per machine — secrets never sync)
-YT_DATA_DIR=/home/you/yt-briefing-data
+YT_BRIEFING_DATA_DIR=/home/you/yt-briefing-data
 ```
 
 ```bash
@@ -38,7 +38,7 @@ npx yt-briefing init                     # onboard into this folder (or move exi
 git add -A && git commit -m "initial" && git push -u origin main
 ```
 
-On the second machine: clone that repo, set the same `YT_DATA_DIR`, drop in your `.env`.
+On the second machine: clone that repo, set the same `YT_BRIEFING_DATA_DIR`, drop in your `.env`.
 
 ---
 
@@ -71,7 +71,7 @@ Save as `yt-sync.sh` (anywhere), `chmod +x`:
 #!/usr/bin/env bash
 # Persist yt-briefing state to git, sync-safe across machines. Best-effort, never blocks.
 set -uo pipefail
-DATA="${YT_DATA_DIR:-$PWD/.yt-briefing/data}"   # the folder you version (default: in-project)
+DATA="${YT_BRIEFING_DATA_DIR:-$PWD/.yt-briefing/data}"   # the folder you version (default: in-project)
 cd "$DATA" || exit 0
 
 git add channels.md state.md channels/ config.json 2>/dev/null || exit 0
@@ -113,7 +113,7 @@ yt-briefing rate --rating 0 && /path/to/yt-sync.sh
 
 > Optional but recommended: also `git pull --rebase` **before** the first sweep of a session
 > (so a machine starts on the latest cursor), e.g. a `PreToolUse` hook matching
-> `*yt-sweep*--reset*`, or just `cd "$YT_DATA_DIR" && git pull --rebase` before you start.
+> `*yt-sweep*--reset*`, or just `cd "$YT_BRIEFING_DATA_DIR" && git pull --rebase` before you start.
 
 ---
 

package/docs/warp-proxy.md

@@ -38,10 +38,10 @@ either; we use HTTP.
 
 ```bash
 # .env
-YT_PROXY=http://127.0.0.1:1080
+YT_BRIEFING_PROXY=http://127.0.0.1:1080
 ```
 
-yt-briefing reads `YT_PROXY` and routes all yt-dlp traffic through it. No env var → direct
+yt-briefing reads `YT_BRIEFING_PROXY` and routes all yt-dlp traffic through it. No env var → direct
 fetch (the residential default).
 
 ### Health check

package/package.json

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