yt-briefing 0.1.0

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

@@ -0,0 +1,54 @@
+---
+name: yt
+description: Briefing from the YouTube channels you follow — the engine sweeps each channel, filters videos in two stages (title, then transcript+content), and lazily yields one video to rate per call. This skill is a thin loop that shows the summary and collects the rating (via AskUserQuestion), which writes durable signal straight into the channel profile. Summaries and the rating question use the language chosen at onboarding.
+---
+
+## How it works
+
+`src/yt-sweep.ts` is **the whole engine**: channel sweep, filters (title filter, then content filter on the transcript via the LLM API), and skip handling — all inside, lazy. The only state it does **not** write is the rating itself — that's `yt-rating.ts` in step D. This skill **does not run filters, read profiles, or format summaries** — it runs the script, pastes the summary, collects the rating.
+
+`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`.
+
+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.
+
+## Rating language
+
+Read `data/config.json` → `output_lang` once at the start of the loop. Phrase the rating **question text** and **option descriptions** in that language. The two button **labels** stay the short English words `OK` / `Weak` (deliberately universal). Summaries are already written in `output_lang` by the engine — paste them verbatim.
+
+## Rating loop
+
+```
+out = JSON.parse(`bun run src/yt-sweep.ts --reset`)   // Bash — first call: --reset rebuilds the queue fresh
+while true:
+  out.status:
+    "done"          → sweep finished — tell the user, stop
+    "rate_limited"  → transcript fetch blocked (usually a blocked egress IP) — tell the user, stop; recovery in README.md → Proxy
+    "rating_needed" → steps A–E
+```
+
+**On `rating_needed` — literally:**
+
+- **A.** Take `out.summary` (markdown) and `out.pending` (metadata).
+- **B.** In the same turn, as **your chat text** (NOT command output — the UI does not show it), paste `summary` **verbatim**: no paraphrase, no shortening, no comment, no "see above". The user must see it before the popup. _(If the user says "I don't see the summary" — you skipped B.)_
+- **C.** In the same message call `AskUserQuestion` — **1 call, 1 question** (everything in one step), phrased in `output_lang`:
+  - The question (e.g. "Rating?") with two options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles). The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**. There is **no positive rating** — keeping the channel is the implicit positive; you only down-rate noise (`0`) or steer with a comment.
+  - **Other** is the comment / stop channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. Otherwise it is a **comment**: **distill** the user's raw text into a clean, generalizable rule, and infer the rating — clearly negative → `0`, otherwise → `1`.
+- **D.** Act on the answer:
+  - `stop` / dismissed → **end the loop** (state already on disk).
+  - A rating option → `bun run src/yt-rating.ts --rating <1|0>`.
+  - A comment (Other, not `stop`) → `bun run src/yt-rating.ts --rating <inferred 1|0> --comment "<distilled rule>"`.
+
+  In every non-stop case **pass only the rating (+ comment)**; the script reads channel/id/title/type from `data/.cache/pending.json`. The write is **immediate and durable — no consolidation**: `rating=0` appends to `## Skip titles` (title filter learns to skip such titles from the next run) and a comment appends the rule to `## Notes` (seen by both filters). A neutral `1` writes nothing — it only bumps the state cursor.
+- **E.** Re-run `bun run src/yt-sweep.ts` **bare** (no `--reset` — resumes the same queue; only the loop's first call uses `--reset`). Its JSON becomes the next iteration's `out` — back to the top of the loop.
+
+## No consolidation
+
+There is no post-loop step. Each rating is **durable immediately**: `yt-rating.ts` writes `rating=0` straight to `## Skip titles` and a comment straight to `## Notes` (FIFO-capped, de-duplicated). `rating=1` only bumps the cursor. The title filter reads those sections live, so the signal takes effect on the very next sweep — nothing to flush, batch, or trigger.
+
+## Rules
+
+- **Language:** question text, option descriptions, and loop messages follow `output_lang`; the two rating **labels** are `OK` / `Weak`. Summaries are written in `output_lang` by the content-filter prompt in the engine — not here.
+- **Transcripts:** never paste a raw transcript into chat; the summary is the artifact.
+- **Resuming:** the skill can be re-run any time — `data/state.md` is the source of truth, so a re-run always skips what's already rated. A queue from a previous day self-invalidates; the loop's first call passes `--reset` to also force a **same-day** rebuild, catching videos published since that morning's queue.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michał Ryzio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# 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.
+
+It also gets better the more you use it. You give each summary 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.
+
+## Setup
+
+You'll need Node 18+ or Bun, a YouTube Data API v3 key, an LLM key (a
+[free Gemini key](https://aistudio.google.com/apikey) works, see [Providers](#providers)), and
+a tool that runs skills: [Claude Code](https://claude.com/claude-code),
+[Cursor](https://cursor.com), or anything else that loads `SKILL.md`.
+
+1. Install yt-dlp (it pulls the subtitles):
+
+| OS | Command |
+|----|---------|
+| macOS | `brew install yt-dlp` |
+| Windows | `winget install yt-dlp` |
+| Linux / any Python | `pipx install yt-dlp` |
+
+Keep it current with `yt-dlp -U`. YouTube changes often.
+
+2. Add the package with any package manager:
+
+```bash
+npm  i   yt-briefing
+pnpm add yt-briefing
+yarn add yt-briefing
+bun  add yt-briefing
+```
+
+3. 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`.
+
+## Run it
+
+Open your project in Claude Code or Cursor and run `/yt`. If it's not listed, start a fresh
+session. To install the skill again for another tool or project, run
+`npx yt-briefing install-skill`.
+
+## Providers
+
+Any OpenAI-compatible endpoint works. Gemini 2.5 Flash is the easy default. It's fast, cheap,
+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
+```
+
+> On the free tier Gemini sometimes returns a "model is overloaded / high demand" error. Retry,
+> 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`).
+
+## 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,
+not through the coding agent's own model. Two reasons.
+
+Speed. The engine works ahead in the background. It expands channels in parallel and starts
+summarizing the next video while you rate the current one, so the following step is usually
+ready with no wait. An agent's turn-by-turn loop cannot prefetch like that, and every step pays
+its own cold start, which adds up across a whole queue.
+
+Compatibility. A standard API plus a small skill means one engine runs everywhere: Claude Code,
+Cursor, any other tool that loads a skill, or the plain CLI. A tool-native approach would tie it
+to that one tool and one model.
+
+## Why one transcript at a time
+
+yt-briefing pulls transcripts lazily. It fetches the one you are about to read, warms the next
+one in the background while you rate, and stops there. It never grabs the whole queue up front.
+
+That pacing is deliberate. Pulling many transcripts in a quick burst looks like scraping to
+YouTube and gets your IP rate-limited or blocked, which is easy to hit on a server. Fetching
+them at the speed you actually work through the queue keeps you under the radar and the queue
+flowing.
+
+## Sync across machines
+
+Your state is plain files in `.yt-briefing/data/`. Version that folder (or point `YT_DATA_DIR`
+at a separate private repo) and commit after each rating. Recipe:
+[docs/sync-across-machines.md](./docs/sync-across-machines.md).
+
+## Running on a VPS
+
+YouTube blocks datacenter IPs, so transcript fetches fail on most servers. Route them through a
+free Cloudflare WARP proxy. See [docs/warp-proxy.md](./docs/warp-proxy.md).
+
+## License
+
+MIT, see [LICENSE](./LICENSE).

package/data.example/.gitattributes

@@ -0,0 +1,7 @@
+# Copy this into your *data* repo (the folder YT_DATA_DIR points at) if you sync state
+# across machines. See docs/sync-across-machines.md.
+#
+# Channel profiles are append-only logs (ratings → ## Skip titles / ## Notes). Union merge
+# keeps BOTH machines' additions instead of conflicting. state.md is intentionally NOT
+# union-merged (it's a table — union would garble rows; a real collision should surface).
+channels/*.md merge=union

package/data.example/README.md

@@ -0,0 +1,19 @@
+# data.example — what onboarding generates
+
+`bun run init` creates a real `data/` directory next to this one. This folder is a
+reference for the shape of that data, and a home for the channel-profile template.
+
+```
+data/
+├── config.json          { "output_lang": "English" }   ← your summary/rating language
+├── channels.md          the channels you follow (a flat list)
+├── state.md             per-channel per-type cursor (last video seen of each type)
+├── channels/
+│   ├── _template.md     the profile section template (see this folder)
+│   └── <slug>.md        one profile per channel — its policy, skip-titles, notes
+└── .cache/              throwaway session state (queue/pending/prefetch); safe to delete
+```
+
+Everything is plain Markdown / JSON. After onboarding you can edit any of it by hand —
+add a channel, tighten a `## Channel policy`, or curate `## Notes`. The two filters pick
+up the changes on the next sweep. See `channels/_template.md` for the section conventions.

package/data.example/channels/_template.md

@@ -0,0 +1,45 @@
+---
+type: yt-channel-profile-template
+description: Section template for a channel profile. A section exists only when it has real content — never placeholders. An empty profile is just frontmatter + heading.
+---
+
+# Channel profile — section template
+
+A channel profile is the durable memory of what's worth watching on a channel. It feeds the engine's two filters (`src/yt-sweep.ts`):
+
+- **Title filter** (keep/skip *before* fetching the transcript) reads: `## Skip titles` (+ rules in `## Notes`). Keep-by-default — it only learns *what to drop* (there is no positive list).
+- **Content filter** (writing the summary) gets the **whole profile**; it leans on `## Channel policy`, `## Summary format`, `## Cut sections`, `## Episode types`, `## Notes`.
+
+Frontmatter (always):
+
+```yaml
+---
+type: yt-channel-profile
+name: <slug>-profile
+channel: @Handle
+channel_url: https://www.youtube.com/@Handle
+updated: YYYY-MM-DD
+sessions_observed: <int>
+---
+```
+
+Optional sections. **A section exists ⟺ it has content.** Don't create empty placeholders.
+
+| Section | Function | Source |
+|---|---|---|
+| `## Channel policy` | Per-channel base policy — short, conceptual: *what to pay attention to on this channel.* | By hand (optional) |
+| `## Summary format` | Deviation from the default (numbered thematic sections). Use it when a channel needs a different style (headline-only, "what it was about", per-segment digest). | By hand |
+| `## Episode types` | Taxonomy of formats (solo / interview / report / multi-segment). Steers summary style per type. | By hand |
+| `## Skip titles` | **Negative** few-shots for the title filter (keep-by-default; learn only what to drop). FIFO cap 10. Format: `- "<title>" — <type>`. | `yt-rating.ts` on `rating=0` |
+| `## Cut sections` | Typical intro/outro/sponsor segments to drop before summarizing. Cap 5. | By hand |
+| `## Notes` | Durable rules: hard flags, edge cases, links (e.g. a sibling channel's mirror profile). **The permanent home for rules distilled from comments.** | By hand + `yt-rating.ts` on a comment |
+
+## Rating scale
+
+Three signals (UI: one step, two buttons + `Other` for a comment). **The write is immediate and durable — no buffer, no consolidation:**
+
+- **`1` — neutral.** Watched, no signal. **Zero effect** — only bumps the cursor in `state.md` (video checked off); writes nothing to the profile.
+- **`0` — worthless.** **Immediately** → `## Skip titles` (cap 10); the title filter learns to skip such titles from the very next sweep.
+- **comment** — a generalizable rule. **Immediately** → `## Notes` (seen by both filters). The agent distills the user's raw comment into a clean rule before writing.
+
+There is no positive rating — keeping the channel subscribed is the implicit "plus".

package/dist/bootstrap.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+/**
+ * bootstrap.ts — interactive onboarding wizard. Run once after install:
+ *
+ *   bun run init        (or: yt-briefing init)
+ *
+ * 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
+ *      → DATA_DIR/channels.md, DATA_DIR/state.md, DATA_DIR/channels/<slug>.md
+ *
+ * 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 { DATA_DIR, 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 = '') => {
+    const a = question(def ? `${q} [${def}]:` : `${q}:`).trim();
+    return a || def;
+};
+const askYN = (q, def = true) => {
+    const a = ask(`${q} (${def ? 'Y/n' : 'y/N'})`).toLowerCase();
+    if (!a)
+        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)) {
+        console.log(`  Existing data found at ${DATA_DIR}`);
+        if (!askYN('  Overwrite it?', false)) {
+            console.log('  Aborted — nothing changed.\n');
+            return;
+        }
+        console.log('');
+    }
+    // 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('  LLM_BASE_URL', 'http://localhost:11434/v1');
+        llmModel = ask('  LLM_MODEL', 'llama3.1');
+        llmKey = ask('  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');
+    console.log('\n  4) Proxy (optional — only needed on datacenter/VPS IPs; see docs/warp-proxy.md)');
+    const ytProxy = ask('  YT_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).
+    console.log('\n  5) 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.');
+    console.log('     Each channel learns what to skip as you rate it.\n');
+    const channels = [];
+    while (true) {
+        const raw = ask('  Channel (blank to finish)');
+        if (!raw)
+            break;
+        const handle = normalizeHandle(raw);
+        if (!handle) {
+            console.log(`  ! couldn't read a handle from "${raw}" — use @name or the channel URL.\n`);
+            continue;
+        }
+        const slug = slugify(handle);
+        if (channels.some(c => c.slug === slug)) {
+            console.log(`  ! ${handle} already added — skipping.\n`);
+            continue;
+        }
+        channels.push({ handle, slug });
+        console.log(`  ✓ ${handle}\n`);
+    }
+    if (channels.length === 0) {
+        console.log('\n  No channels added — you can add them later by editing data/channels.md.\n');
+    }
+    // 6. 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).
+    // Claude Code reads .claude/skills/ (already shipped here); Cursor reads .cursor/skills/.
+    // 1/2 = known agents; 3 = any other agent (a project folder you name).
+    console.log('\n  6) Which agent will you run /yt in?');
+    console.log('       1) Claude Code      2) Cursor      3) 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('  Folder to install the skill into', customSkillDirDefault());
+    // 7. Write everything --------------------------------------------------------
+    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}`,
+        '',
+    ].join('\n');
+    writeFileSync(ENV_PATH, envBody, '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');
+    }
+    console.log('  ' + '─'.repeat(40));
+    console.log(`  Done. Wrote:`);
+    console.log(`    ${ENV_PATH}`);
+    console.log(`    ${CONFIG_JSON}`);
+    console.log(`    ${CHANNELS_MD}`);
+    console.log(`    ${STATE_MD}`);
+    console.log(`    ${channels.length} profile(s) in ${CHANNELS_DIR}/`);
+    // Install the /yt skill for the chosen agent (step 6), into THIS project — process.cwd(),
+    // i.e. wherever you ran the command (the package clone in dev, or your own project when the
+    // package is a dependency). The command baked in is the shipped `bun run src` only for the
+    // dev-in-clone case; otherwise the compiled `dist/` command (so a consumed package works).
+    const agent = AGENTS[agentKey];
+    try {
+        const target = agent
+            ? installSkill(projectSkillDir(agentKey, process.cwd()), /* dist */ !isPackageDevCwd())
+            : installSkill(customDir, /* dist */ true);
+        console.log(`    /yt skill → ${target}`);
+    }
+    catch (e) {
+        console.log(`  ! Couldn't install the skill (${e.message}) — run  yt-briefing install-skill  later.`);
+    }
+    console.log('\n  Next:');
+    console.log(`    1. Open this folder in ${agent ? agent.name : 'your agent'}.`);
+    console.log('    2. Start a new chat and type  /yt');
+    console.log('\n  No agent? Run it in the terminal instead — see the README.\n');
+}
+try {
+    main();
+}
+catch (err) {
+    console.error(err);
+    process.exit(1);
+}

package/dist/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Thin CLI dispatcher so the tool is usable as `yt-briefing <cmd>` once installed,
+ * mirroring the `bun run <script>` entry points. Each subcommand just forwards to the
+ * matching engine script with the same runtime as this process (`process.execPath` — Node
+ * or Bun), passing remaining args through.
+ *
+ *   yt-briefing init                       interactive onboarding wizard
+ *   yt-briefing install-skill              install the /yt skill into a coding agent
+ *   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
+ */
+import { spawnSync } from 'node:child_process';
+import { script } from "./lib/paths.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const TARGETS = {
+    init: 'bootstrap',
+    'install-skill': 'install-skill',
+    sweep: 'yt-sweep',
+    rate: 'yt-rating',
+    transcribe: 'yt-transcript',
+};
+if (!cmd || !TARGETS[cmd]) {
+    console.error('Usage: yt-briefing <init|install-skill|sweep|rate|transcribe> [args...]');
+    process.exit(cmd ? 1 : 0);
+}
+const res = spawnSync(process.execPath, [script(TARGETS[cmd]), ...rest], { stdio: 'inherit' });
+process.exit(res.status ?? 1);

package/dist/install-skill.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * install-skill — copy the `/yt` skill into a coding agent's skills directory so the
+ * agent detects it. For any target that isn't this package under Bun, the command is baked to
+ * `"<this runtime>" "<abs>/dist/X.js"` (the compiled build), so it works no matter the agent's
+ * working directory or runtime (the engine resolves data/.env from its own location).
+ *
+ *   yt-briefing install-skill        # interactive: pick agent + scope
+ *
+ * `bun run init` already installs this skill into the project as its final step; this
+ * standalone command is for re-installing, a different project, or a second agent. There is
+ * deliberately no home-global install — the skill lives with the project that uses it.
+ *
+ * Both Claude Code and Cursor load `SKILL.md` skills and invoke them as `/<name>`.
+ * Cursor also reads `.claude/skills/` for compatibility, so the copy this package already
+ * ships often works in both — this command just (re)places it where you want.
+ */
+import { AGENTS, installSkill, projectSkillDir, customSkillDirDefault, isPackageDevCwd } from "./lib/skill-install.js";
+import { question } from "./lib/prompt.js";
+const ask = (q, def = '') => question(def ? `${q} [${def}]:` : `${q}:`).trim() || def;
+function done(target) {
+    console.log(`\n  ✓ Installed → ${target}`);
+    console.log('  Start a fresh agent session, then run  /yt\n');
+}
+// 1) which agent → which skills subdir
+console.log('\n  Install the /yt skill — which agent?\n');
+console.log('    1) Claude Code');
+console.log('    2) Cursor   (also reads Claude\'s .claude/skills)');
+console.log('    3) Custom folder (any other agent)\n');
+const agentKey = ask('  Agent', '1');
+const agent = AGENTS[agentKey];
+// 3) Custom — write SKILL.md straight into a folder the user names (their agent's skills dir).
+// Arbitrary location → bake the absolute dist command so it works whatever the agent's cwd is.
+if (!agent) {
+    done(installSkill(ask('  Folder to install the skill into', customSkillDirDefault()), true));
+    process.exit(0);
+}
+// 2) Known agent → which project (default: the current folder). No home-global option by
+// design — the skill is always scoped to a project that uses it.
+console.log(`\n  ${agent.name} — which project?\n`);
+console.log('    1) This project (current folder) — recommended');
+console.log('    2) Another project folder\n');
+if (ask('  Where', '1') === '2') {
+    // A different project → the agent's cwd won't be the package, so bake the absolute dist command.
+    done(installSkill(projectSkillDir(agentKey, ask('  Project folder', process.cwd())), true));
+}
+else {
+    // Current folder: shipped `bun run src` only when developing in the package clone under Bun;
+    // otherwise (incl. consuming the package as a dependency) bake the compiled dist command.
+    done(installSkill(projectSkillDir(agentKey, process.cwd()), !isPackageDevCwd()));
+}

package/dist/lib/config.js

@@ -0,0 +1,23 @@
+/**
+ * User preferences for yt-briefing — currently just the output language, decided at
+ * onboarding and stored in DATA_DIR/config.json. Kept separate from .env on purpose:
+ * .env holds secrets (API keys, proxy), config.json holds non-secret preferences that
+ * both the engine and the agent (skill) read. The skill reads `output_lang` to ask the
+ * rating question in the user's language; the engine reads it to write summaries in it.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { CONFIG_JSON } from "./paths.js";
+export function loadConfig() {
+    if (existsSync(CONFIG_JSON)) {
+        try {
+            const c = JSON.parse(readFileSync(CONFIG_JSON, 'utf8'));
+            if (typeof c.output_lang === 'string' && c.output_lang.trim()) {
+                return { output_lang: c.output_lang.trim() };
+            }
+        }
+        catch { /* malformed → fall through to env/default */ }
+    }
+    return { output_lang: process.env.OUTPUT_LANG?.trim() || 'English' };
+}
+/** The language summaries and ratings are written in. Default English. */
+export const outputLang = () => loadConfig().output_lang;