yt-briefing 0.1.0 → 0.3.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
@@ -43,6 +53,14 @@ 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`.
 
+Add or remove channels anytime:
+
+```bash
+npx yt-briefing add @handle https://youtube.com/@another   # one or more, handle or URL
+npx yt-briefing remove @handle                              # also deletes its learned profile
+npx yt-briefing list                                        # show the current list
+```
+
 ## Run it
 
 Open your project in Claude Code or Cursor and run `/yt`. If it's not listed, start a fresh
@@ -55,9 +73,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 +110,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,9 +14,11 @@
  * 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";
+import { normalizeHandle, slugify, serializeChannels, serializeState, profileBody, baselineStateRow } from "./lib/channels.js";
 const ask = (q, def = '') => {
     const a = question(def ? `${q} [${def}]:` : `${q}:`).trim();
     return a || def;
@@ -27,35 +29,6 @@ const askYN = (q, def = true) => {
         return def;
     return a.startsWith('y');
 };
-/**
- * Accept any of: `@betterstack`, `betterstack`, `https://www.youtube.com/@betterstack`
- * (with or without a trailing `/videos` etc.) → canonical `@betterstack`. Returns null if
- * no handle can be read (e.g. a bare `/channel/UC…` URL — ask the user for the @handle).
- */
-function normalizeHandle(input) {
-    let s = input.trim();
-    if (/youtube\.com/i.test(s) || /^https?:\/\//i.test(s)) {
-        const m = s.match(/@[A-Za-z0-9._-]+/); // pull the @handle out of a URL
-        s = m ? m[0] : '';
-    }
-    s = s.replace(/^@+/, '').replace(/[^A-Za-z0-9._-].*$/, ''); // bare token
-    return s ? `@${s}` : null;
-}
-/** kebab-case slug that also breaks CamelCase: "BetterStack" → "better-stack". */
-function slugify(s) {
-    return s
-        .replace(/@/g, '')
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .replace(/[^A-Za-z0-9]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '')
-        .toLowerCase();
-}
-const today = new Date().toISOString().slice(0, 10);
-// Fresh channels start "baseline": the first sweep surfaces the latest upload per type.
-// updated is set this far back so that window actually contains a recent video.
-const BASELINE_LOOKBACK_DAYS = 60;
-const lookback = new Date(Date.now() - BASELINE_LOOKBACK_DAYS * 864e5).toISOString().slice(0, 10);
 function main() {
     console.log('\n  yt-briefing — onboarding\n  ' + '─'.repeat(40) + '\n');
     if (existsSync(CHANNELS_MD)) {
@@ -94,15 +67,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,68 +119,28 @@ 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.
-    const chParts = [
-        '---',
-        'type: yt-config',
-        'name: yt-channels',
-        'description: The channels you follow. Per-channel learned signal lives in channels/<slug>.md.',
-        `updated: ${today}`,
-        '---',
-        '',
-        '# Channels',
-        '',
-    ];
-    for (const c of channels) {
-        chParts.push(`- [${c.handle}](https://www.youtube.com/${c.handle}) → [[channels/${c.slug}]]`);
-    }
-    writeFileSync(CHANNELS_MD, chParts.join('\n') + '\n', 'utf8');
-    // state.md — one flat table (baseline rows: pointers "—", updated = lookback so the first
-    // sweep finds the latest upload per type).
-    const stParts = [
-        '---',
-        'type: yt-state',
-        'name: yt-state',
-        'description: Per-channel per-type cursor. The sweep reads and updates it.',
-        `updated: ${today}`,
-        '---',
-        '',
-        '# State',
-        '',
-        '| Channel | last_longform_id | last_short_id | last_live_id | updated | session |',
-        '|---|---|---|---|---|---|',
-    ];
-    for (const c of channels) {
-        stParts.push(`| ${c.handle} | — | — | — | ${lookback} | 0 |`);
-    }
-    writeFileSync(STATE_MD, stParts.join('\n') + '\n', 'utf8');
-    // per-channel profiles
-    for (const c of channels) {
-        const pParts = [
-            '---',
-            'type: yt-channel-profile',
-            `name: ${c.slug}-profile`,
-            `channel: ${c.handle}`,
-            `channel_url: https://www.youtube.com/${c.handle}`,
-            `updated: ${today}`,
-            'sessions_observed: 0',
-            '---',
-            '',
-            `# ${c.handle} — Profile`,
-            '',
-        ];
-        writeFileSync(profilePath(c.slug), pParts.join('\n') + '\n', 'utf8');
-    }
+    // channels.md / state.md / per-channel profiles — via the shared serializers, so the
+    // on-disk format is identical to what the add/remove command writes (single source).
+    writeFileSync(CHANNELS_MD, serializeChannels(channels), 'utf8');
+    writeFileSync(STATE_MD, serializeState(channels.map(c => baselineStateRow(c.handle))), 'utf8');
+    for (const c of channels)
+        writeFileSync(profilePath(c.slug), profileBody(c.handle, c.slug), 'utf8');
     console.log('  ' + '─'.repeat(40));
     console.log(`  Done. Wrote:`);
     console.log(`    ${ENV_PATH}`);

package/dist/cli.js

@@ -7,6 +7,8 @@
  *
  *   yt-briefing init                       interactive onboarding wizard
  *   yt-briefing install-skill              install the /yt skill into a coding agent
+ *   yt-briefing add|remove <@handle|url>   add or remove channels (also list)
+ *   yt-briefing list                       list the channels you follow
  *   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
@@ -14,6 +16,8 @@
 import { spawnSync } from 'node:child_process';
 import { script } from "./lib/paths.js";
 const [cmd, ...rest] = process.argv.slice(2);
+// Subcommand → engine script. Channel actions all route to yt-channels with the action
+// passed through as its first arg.
 const TARGETS = {
     init: 'bootstrap',
     'install-skill': 'install-skill',
@@ -21,9 +25,15 @@ const TARGETS = {
     rate: 'yt-rating',
     transcribe: 'yt-transcript',
 };
-if (!cmd || !TARGETS[cmd]) {
-    console.error('Usage: yt-briefing <init|install-skill|sweep|rate|transcribe> [args...]');
+const CHANNEL_ACTIONS = new Set(['add', 'remove', 'list']);
+let argv = null;
+if (cmd && CHANNEL_ACTIONS.has(cmd))
+    argv = [script('yt-channels'), cmd, ...rest];
+else if (cmd && TARGETS[cmd])
+    argv = [script(TARGETS[cmd]), ...rest];
+if (!argv) {
+    console.error('Usage: yt-briefing <init|install-skill|add|remove|list|sweep|rate|transcribe> [args...]');
     process.exit(cmd ? 1 : 0);
 }
-const res = spawnSync(process.execPath, [script(TARGETS[cmd]), ...rest], { stdio: 'inherit' });
+const res = spawnSync(process.execPath, argv, { stdio: 'inherit' });
 process.exit(res.status ?? 1);

package/dist/lib/channels.js

@@ -0,0 +1,82 @@
+export const BASELINE_LOOKBACK_DAYS = 60;
+export const today = () => new Date().toISOString().slice(0, 10);
+// Fresh channels start "baseline": updated is set this far back so the first sweep's window
+// still contains a recent upload per type (which becomes the starting point).
+export const lookbackDate = () => new Date(Date.now() - BASELINE_LOOKBACK_DAYS * 864e5).toISOString().slice(0, 10);
+export const channelUrl = (handle) => `https://www.youtube.com/${handle}`;
+/**
+ * Accept any of: `@betterstack`, `betterstack`, `https://www.youtube.com/@betterstack`
+ * (with or without a trailing `/videos` etc.) → canonical `@betterstack`. Returns null if no
+ * handle can be read (e.g. a bare `/channel/UC…` URL — ask the user for the @handle).
+ */
+export function normalizeHandle(input) {
+    let s = input.trim();
+    if (/youtube\.com/i.test(s) || /^https?:\/\//i.test(s)) {
+        const m = s.match(/@[\p{L}\p{N}._-]+/u); // pull the @handle out of a URL (Unicode-aware)
+        s = m ? m[0] : '';
+    }
+    s = s.replace(/^@+/, '');
+    // Keep the leading run of handle chars — letters (any script, e.g. ł), digits, . _ - —
+    // so non-ASCII handles like @DziałZagraniczny survive instead of truncating at the first ł.
+    const m = s.match(/^[\p{L}\p{N}._-]+/u);
+    s = m ? m[0] : '';
+    return s ? `@${s}` : null;
+}
+/**
+ * kebab-case slug that also breaks CamelCase: "BetterStack" → "better-stack". Diacritics are
+ * folded to ASCII so non-Latin handles get readable slugs: "DziałZagraniczny" → "dzial-zagraniczny"
+ * (ł has no NFD decomposition, so it's mapped explicitly; the rest go through NFD).
+ */
+export function slugify(s) {
+    return s
+        .replace(/@/g, '')
+        .replace(/ł/g, 'l').replace(/Ł/g, 'L')
+        .normalize('NFD').replace(/[̀-ͯ]/g, '') // strip combining diacritics (ą→a, é→e, …)
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+/** A fresh state row for a just-added channel: no cursors yet, dated back to the lookback. */
+export const baselineStateRow = (handle) => ({
+    handle,
+    last_longform_id: null,
+    last_short_id: null,
+    last_live_id: null,
+    updated: lookbackDate(),
+    session: 0,
+});
+/** channels.md — a flat list of the channels you follow. */
+export function serializeChannels(entries, date = today()) {
+    const parts = [
+        '---', 'type: yt-config', 'name: yt-channels',
+        'description: The channels you follow. Per-channel learned signal lives in channels/<slug>.md.',
+        `updated: ${date}`, '---', '', '# Channels', '',
+    ];
+    for (const c of entries)
+        parts.push(`- [${c.handle}](${channelUrl(c.handle)}) → [[channels/${c.slug}]]`);
+    return parts.join('\n') + '\n';
+}
+/** state.md — one flat table; baseline rows use "—" pointers and the lookback date. */
+export function serializeState(rows, date = today()) {
+    const parts = [
+        '---', 'type: yt-state', 'name: yt-state',
+        'description: Per-channel per-type cursor. The sweep reads and updates it.',
+        `updated: ${date}`, '---', '', '# State', '',
+        '| Channel | last_longform_id | last_short_id | last_live_id | updated | session |',
+        '|---|---|---|---|---|---|',
+    ];
+    for (const r of rows) {
+        parts.push(`| ${r.handle} | ${r.last_longform_id ?? '—'} | ${r.last_short_id ?? '—'} | ${r.last_live_id ?? '—'} | ${r.updated ?? lookbackDate()} | ${r.session} |`);
+    }
+    return parts.join('\n') + '\n';
+}
+/** A fresh, empty channel profile (learned signal accumulates here as you rate). */
+export function profileBody(handle, slug, date = today()) {
+    return [
+        '---', 'type: yt-channel-profile', `name: ${slug}-profile`,
+        `channel: ${handle}`, `channel_url: ${channelUrl(handle)}`, `updated: ${date}`,
+        'sessions_observed: 0', '---', '', `# ${handle} — Profile`, '',
+    ].join('\n') + '\n';
+}

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-channels.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * Add, remove, or list the channels you follow — keeping channels.md, state.md, and the
+ * per-channel profile in sync. Driven by the CLI: `yt-briefing add|remove|list ...`.
+ *
+ *   yt-briefing add @foo https://youtube.com/@bar   # add one or more (handle or URL)
+ *   yt-briefing remove @foo                          # remove (also deletes its profile)
+ *   yt-briefing list                                 # show the current list
+ *
+ * Adding a channel starts it at "baseline" (next sweep surfaces the latest upload per type);
+ * removing one drops its row and learned profile. Existing channels' cursors are untouched.
+ */
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { CHANNELS_MD, STATE_MD, profilePath } from "./lib/paths.js";
+import { parseChannels, parseState } from "./lib/yt-lib.js";
+import { normalizeHandle, slugify, serializeChannels, serializeState, profileBody, baselineStateRow, } from "./lib/channels.js";
+const [action, ...args] = process.argv.slice(2);
+if (!existsSync(CHANNELS_MD) || !existsSync(STATE_MD)) {
+    console.error('No channel list yet — run onboarding first: yt-briefing init');
+    process.exit(1);
+}
+let entries = parseChannels(readFileSync(CHANNELS_MD, 'utf8'));
+if (action === 'list') {
+    for (const e of entries)
+        console.log(`  ${e.handle}`);
+    console.log(`\n  ${entries.length} channel(s).`);
+    process.exit(0);
+}
+if ((action !== 'add' && action !== 'remove') || args.length === 0) {
+    console.error('Usage: yt-briefing add|remove <@handle | url> [...]   ·   yt-briefing list');
+    process.exit(1);
+}
+let rows = parseState(readFileSync(STATE_MD, 'utf8'));
+let changed = 0;
+for (const raw of args) {
+    const handle = normalizeHandle(raw);
+    if (!handle) {
+        console.log(`  ! couldn't read a handle from "${raw}" — use @name or the channel URL`);
+        continue;
+    }
+    const slug = slugify(handle);
+    const exists = entries.some(e => e.slug === slug);
+    if (action === 'add') {
+        if (exists) {
+            console.log(`  • ${handle} already on the list — skipping`);
+            continue;
+        }
+        entries.push({ handle, slug });
+        rows.push(baselineStateRow(handle));
+        writeFileSync(profilePath(slug), profileBody(handle, slug), 'utf8');
+        console.log(`  + ${handle}`);
+        changed++;
+    }
+    else {
+        if (!exists) {
+            console.log(`  • ${handle} not on the list — skipping`);
+            continue;
+        }
+        const entry = entries.find(e => e.slug === slug);
+        entries = entries.filter(e => e.slug !== slug);
+        rows = rows.filter(r => r.handle !== entry.handle);
+        try {
+            rmSync(profilePath(slug));
+        }
+        catch { /* profile already gone */ }
+        console.log(`  − ${handle}  (profile deleted)`);
+        changed++;
+    }
+}
+if (changed) {
+    writeFileSync(CHANNELS_MD, serializeChannels(entries), 'utf8');
+    writeFileSync(STATE_MD, serializeState(rows), 'utf8');
+}
+console.log(`\n  ${entries.length} channel(s) now. The next sweep picks up the change.`);

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