yt-briefing 0.15.0 → 1.0.0

package/dist/yt-sweep.js

@@ -12,7 +12,7 @@
  *   bun src/yt-sweep.ts --fill                 (internal: detached queue builder)
  *
  * Output (stdout, single JSON line):
- *   {"status":"rating_needed","summary":"<md>","pending":{channel,videoId,title,type,publishedAt,is_baseline}}
+ *   {"status":"rating_needed","summary":"<md>","pending":{channel,videoId,title,type,publishedAt,is_baseline}}  (+ "lang")
  *   {"status":"done"}
  *   {"status":"rate_limited"}
  *
@@ -49,9 +49,9 @@
  */
 import { readFileSync, writeFileSync, existsSync, rmSync, mkdirSync, renameSync, appendFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_LLM, REQUIRED_YOUTUBE } from "./lib/env.js";
+import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_YOUTUBE } from "./lib/env.js";
 import { parseChannels, parseState, bumpStatePointer, isResolved } from "./lib/yt-lib.js";
-import { chat, getModel } from "./lib/llm.js";
+import { chat, claudeMissing } from "./lib/llm.js";
 import { outputLang } from "./lib/config.js";
 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();
@@ -251,8 +251,6 @@ Output ONLY a raw JSON array (no markdown fences, no explanation):
     try {
         out = await chat(prompt, {
             system: "You are a video title classifier. Output ONLY a raw JSON array as instructed. No markdown fences, no explanation.",
-            model: getModel(),
-            temperature: 0,
         });
     }
     catch {
@@ -303,7 +301,6 @@ Steps:
 5. Output: ONLY the briefing itself OR 'OFFTOPIC: ...'. No preamble, and no meta-commentary about these instructions.`;
     return await chat(prompt, {
         system: `You write channel briefings in ${LANG}, following the task instructions and the channel's standing directives exactly. Output only the briefing or 'OFFTOPIC: <reason>' — no preamble, no meta-commentary about the instructions.`,
-        model: getModel(),
     });
 }
 // ---------- queue build (lazy: list channels now, expand on demand) ----------
@@ -491,7 +488,7 @@ async function advance(queue) {
         writeFileSync(QUEUE_FILE, JSON.stringify(queue));
         // Warm the NEXT video in the background while the user rates this one.
         spawnPrefetch(queue.items[1]);
-        emit({ status: 'rating_needed', summary: result.summary, pending });
+        emit({ status: 'rating_needed', summary: result.summary, pending, lang: LANG });
     }
     // All processed.
     if (existsSync(QUEUE_FILE))
@@ -567,12 +564,15 @@ if (reset) {
 }
 // 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.
+// videos") — the YouTube error is collapsed by the per-channel catch, and a missing `claude` CLI is
+// swallowed by the title-filter's keep-all fallback. Fail fast naming what is missing instead.
 {
-    const missing = missingEnv([...REQUIRED_LLM, ...REQUIRED_YOUTUBE]);
+    const missing = missingEnv(REQUIRED_YOUTUBE);
     if (missing.length)
         emit({ status: 'error', error: missingEnvMessage(missing) });
+    const noClaude = claudeMissing();
+    if (noClaude)
+        emit({ status: 'error', error: noClaude });
 }
 const queue = loadQueue() ?? buildQueue();
 await advance(queue);

package/docs/sync-across-machines.md

@@ -89,31 +89,24 @@ echo "yt-briefing: state NOT pushed — resolve: cd \"$DATA\" && git pull --reba
 exit 0
 ```
 
-Then trigger it after each rating. Two ways, depending on how you run yt-briefing:
-
-**A) Via a coding agent (Claude Code / Cursor)** — add a `PostToolUse` hook that fires after
-the engine runs. In Claude Code's `settings.json`:
+Then point the engine at it. In `.yt-briefing/data/config.json` (the file is in the folder you
+version, so every machine gets the setting):
 
 ```json
 {
-  "hooks": {
-    "PostToolUse": [
-      { "matcher": "Bash",
-        "hooks": [ { "type": "command", "command": "cmd=$(jq -r '.tool_input.command // \"\"'); case \"$cmd\" in *yt-rating*|*yt-sweep*) /path/to/yt-sync.sh ;; esac" } ] }
-    ]
-  }
+  "output_lang": "English",
+  "after_rate": "/path/to/yt-sync.sh"
 }
 ```
 
-**B) Via the CLI** — just call it after `rate`:
-
-```bash
-yt-briefing rate --rating 0 && /path/to/yt-sync.sh
-```
+The engine runs `after_rate` after every recorded rating, from the pane and from the CLI
+(`yt-briefing rate`) alike. It runs detached from the project root, so a slow push never holds the
+next video, and a failing script never fails the rating (the rating is already on disk). The
+engine itself still never runs git: the command is yours.
 
 > 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_BRIEFING_DATA_DIR" && git pull --rebase` before you start.
+> (so a machine starts on the latest cursor), e.g. `cd "$YT_BRIEFING_DATA_DIR" && git pull --rebase`
+> before you open `/yt`, or a `SessionStart` hook that does the same.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yt-briefing",
-  "version": "0.15.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.",
+  "version": "1.0.0",
+  "description": "A self-learning YouTube briefing for Claude Code: it sweeps the channels you follow, filters noise in two stages (title, then transcript), gives you a short briefing of the rest in your language in a pane, and adapts to your ratings — one video at a time.",
   "type": "module",
   "bin": {
     "yt-briefing": "dist/cli.js"
@@ -10,6 +10,8 @@
     "dist",
     "data.example",
     ".claude/skills",
+    "plugin",
+    "!plugin/**/*.test.tsx",
     "docs",
     "README.md",
     "LICENSE"
@@ -32,12 +34,11 @@
   "keywords": [
     "youtube",
     "transcript",
-    "summary",
     "briefing",
-    "llm",
-    "openai-compatible",
-    "agent",
-    "claude"
+    "claude-code",
+    "claude-code-plugin",
+    "claude",
+    "agent"
   ],
   "license": "MIT",
   "repository": {

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "yt-briefing",
+  "version": "1.0.0",
+  "description": "The /yt briefing loop as a Claude Code pane: summary, one-key rating, research hand-off.",
+  "author": { "name": "Michal Ryzio" },
+  "types": "./types/index.d.ts"
+}

package/plugin/hooks/engine.ts

@@ -0,0 +1,4 @@
+// How the pane runs the engine, relative to the project root (the session's working directory).
+// This is the dev-clone form; `yt-briefing install-skill` / `init` rewrites it for the project it
+// installs into (the compiled dist/ under node_modules, with the runtime that ran the installer).
+export const engine = (name: string): string[] => ['bun', `src/${name}.ts`]

package/plugin/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/plugin/hooks/register.tsx

@@ -0,0 +1,199 @@
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Pending, View } from '../types'
+import { engine } from './engine.ts'
+
+// The /yt rating loop as a pane. Every step runs the engine as a subprocess and reads its one-line
+// JSON; the model is not involved unless the person asks for research, which hands the video to
+// the session as a prompt. Ratings and comments are written by the engine, never by this module.
+
+const PANE = 'yt-briefing'
+const view = atom({ plugin: 'yt-briefing', key: 'view' } as const, { phase: 'idle' } as View)
+
+/** A sweep can expand channels, fetch transcripts and summarize; give it the engine's full budget. */
+const SWEEP_MS = 10 * 60_000
+/** A rating is a file write; a raw comment adds one `claude -p` call to distill it. */
+const RATE_MS = 3 * 60_000
+
+type Skip = { channel: string; title: string; reason: string }
+type SweepOut = {
+  status: string
+  summary?: string
+  pending?: Pending
+  lang?: string
+  error?: string
+  skipped?: number
+  skips?: Skip[]
+}
+
+const STATUS_TEXT: Record<string, string> = {
+  done: 'Sweep finished: nothing left to rate.',
+  rate_limited: 'YouTube is blocking this IP (429 / captcha). See README → Proxy.',
+  tooling_error: 'Transcript tooling failed (proxy, yt-dlp or network). See README → Proxy.',
+}
+
+/** The engine prints one JSON line on stdout; take the last non-empty line to be safe. */
+function parseOut(stdout: string): SweepOut {
+  const line = stdout.trim().split('\n').filter(Boolean).pop() ?? ''
+  return JSON.parse(line) as SweepOut
+}
+
+/** Replace the whole view; the one writer for a fresh phase. */
+async function setView($: EngineInterface, next: View) {
+  await update($, view, () => next)
+}
+
+function skipLine(out: SweepOut): string | undefined {
+  if (!out.skipped || !out.skips?.length) return undefined
+  const list = out.skips.map(s => `${s.channel} «${s.title}» — ${s.reason}`).join('; ')
+  return `Skipped ${out.skipped}: ${list}`
+}
+
+/** Advance to the next ratable video and put it (or the end state) in the view. */
+async function sweep($: EngineInterface, reset: boolean) {
+  await setView($, { phase: 'loading' })
+  let out: SweepOut
+  try {
+    const run = await $.process.run([...engine('yt-sweep'), ...(reset ? ['--reset'] : [])], { timeoutMs: SWEEP_MS })
+    out = parseOut(run.stdout)
+  } catch (err) {
+    await setView($, { phase: 'error', message: `The engine did not answer: ${String(err)}` })
+    return
+  }
+  const skipped = skipLine(out)
+  if (out.status === 'rating_needed' && out.summary && out.pending) {
+    await setView($, { phase: 'rating', summary: out.summary, pending: out.pending, lang: out.lang, skipped })
+  } else if (out.status === 'done') {
+    await setView($, { phase: 'done', message: STATUS_TEXT.done, skipped })
+  } else {
+    await setView($, { phase: 'error', message: out.error ?? STATUS_TEXT[out.status] ?? `Engine status: ${out.status}`, skipped })
+  }
+}
+
+/** Record a rating (engine args), then move on; on failure stay on the video and say why. */
+async function rate($: EngineInterface, args: string[], thenNext = true): Promise<{ rule?: string } | null> {
+  const v = await read($, view)
+  if (v.phase !== 'rating' || v.busy) return null
+  await update($, view, cur => ({ ...cur, busy: args[0] === '--raw-comment' ? 'Turning the comment into a rule…' : 'Saving…' }))
+  const run = await $.process.run([...engine('yt-rating'), ...args], { timeoutMs: RATE_MS }).catch(err => ({
+    exitCode: 1, stdout: '', stderr: String(err),
+  }))
+  if (run.exitCode !== 0) {
+    await update($, view, cur => ({ ...cur, busy: undefined }))
+    $.ui.toast(`Rating not saved: ${run.stderr.trim().slice(0, 200) || 'engine error'}`)
+    return null
+  }
+  let result: { rule?: string } = {}
+  try { result = JSON.parse(run.stdout.trim().split('\n').pop() ?? '{}') } catch { /* rating is on disk */ }
+  if (thenNext) void sweep($, false)
+  return result
+}
+
+/** Research: mark the video seen, close the pane and hand the video to the session. */
+async function research($: EngineInterface, question?: string) {
+  const v = await read($, view)
+  if (!v.pending || !v.summary) return
+  if (!(await rate($, ['--rating', '1'], false))) return
+  await $.ui.close({ id: PANE })
+  const p = v.pending
+  const transcript = [...engine('yt-transcript'), p.videoId, '--lang', 'auto'].join(' ')
+  const ask = question
+    ? `My question: ${question}`
+    : 'Ask me first what I want to dig into.'
+  await $.prompt.submit({
+    asUser: true,
+    text: [
+      `Let's research this video together: ${p.channel} — "${p.title}" (${p.videoId}, ${p.type}).`,
+      '',
+      'Its briefing:',
+      v.summary,
+      '',
+      `For anything beyond the briefing, pull the full transcript with \`${transcript}\` and work from the tool result; never paste the transcript into the chat, quote only short passages. Keep what the video claims separate from what you verify yourself, and use whatever the question needs (my project, the web). Answer in ${v.lang ?? 'English'}.`,
+      ask,
+      '',
+      'If it turns out to be hype, record it with `' + [...engine('yt-rating'), '--rating', '0'].join(' ') + '`; a lasting preference about this channel goes in with `' + [...engine('yt-rating'), '--raw-comment', '"<what to remember>"'].join(' ') + '`.',
+    ].join('\n'),
+  }).catch(err => $.ui.toast(`Could not hand the video to the session: ${String(err)}`))
+}
+
+async function comment($: EngineInterface, raw: string) {
+  const text = raw.trim()
+  if (!text) return
+  if (text.toLowerCase() === 'stop') return void $.ui.close({ id: PANE })
+  if (text.startsWith('?')) return research($, text.slice(1).trim() || undefined)
+  const saved = await rate($, ['--raw-comment', text])
+  if (saved?.rule) $.ui.toast(`Rule saved: ${saved.rule}`)
+}
+
+
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'yt',
+      description: 'Rate the next videos from the YouTube channels you follow, in a pane',
+    })
+
+    return next(e)
+  })
+
+  on('command.run', { command: 'yt' }, async $ => {
+    await $.ui.open({ id: PANE, title: 'yt-briefing', focus: true, closeOnEscape: true })
+    void sweep($, true)
+
+    return { text: 'Briefing opened in a pane.' }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text, Button, Markdown } = $.ui.resolve(e)
+    const v = await read($, view)
+    const close = () => void $.ui.close({ id: PANE })
+
+    if (v.phase === 'idle' || v.phase === 'loading') {
+      return <Text dimColor>Finding the next video…</Text>
+    }
+
+    if (v.phase !== 'rating') {
+      return (
+        <Box flexDirection="column">
+          {v.skipped && <Text dimColor>{v.skipped}</Text>}
+          <Text>{v.message ?? ''}</Text>
+          <Button key="close" label="Close" hotkey="c" role="dismiss" onPress={close} />
+        </Box>
+      )
+    }
+
+    const idle = !v.busy
+    const buttons = (
+      <Box flexDirection="row" gap={2}>
+        <Button key="ok" label="OK" hotkey="1" variant="primary" dimColor={!idle}
+          onPress={() => void rate($, ['--rating', '1'])} />
+        <Button key="weak" label="Weak" hotkey="2" dimColor={!idle}
+          onPress={() => void rate($, ['--rating', '0'])} />
+        <Button key="research" label="Research" hotkey="3" dimColor={!idle}
+          onPress={() => void research($)} />
+        <Button key="stop" label="Stop" hotkey="4" role="dismiss" onPress={close} />
+      </Box>
+    )
+
+    let field = null
+    if (e.surface !== 'mobile') {
+      const { Input } = $.ui.resolve(e)
+      field = (
+        <Input key="comment" label="Comment" submitLabel="save rule"
+          placeholder="becomes a rule for this channel · ?question = research · stop"
+          onSubmit={value => void comment($, value)} />
+      )
+    }
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        {v.skipped && <Text dimColor>{v.skipped}</Text>}
+        <Markdown text={(v.summary ?? '').slice(0, 10000)} />
+        {v.busy ? <Text dimColor>{v.busy}</Text> : buttons}
+        {field}
+        <Text dimColor>OK = neutral · Weak = teach the filter to skip titles like this · Research = dig into it with Claude</Text>
+      </Box>
+    )
+  })
+}

package/plugin/types/index.d.ts

@@ -0,0 +1,28 @@
+export type Pending = {
+  channel: string
+  videoId: string
+  title: string
+  type: string
+  publishedAt: string
+}
+
+export type View = {
+  phase: 'idle' | 'loading' | 'rating' | 'done' | 'error'
+  /** Briefing markdown of the video awaiting a rating. */
+  summary?: string
+  pending?: Pending
+  /** Language the engine writes in; the research hand-off asks for it too. */
+  lang?: string
+  /** Videos the filters dropped on the way to this one, one line. */
+  skipped?: string
+  /** Error or status text for the done/error phases. */
+  message?: string
+  /** Set while a rating or comment is being written; presses are ignored meanwhile. */
+  busy?: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'yt-briefing': { view: View }
+  }
+}

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

@@ -1,68 +0,0 @@
----
-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. A third option, Research, breaks the loop to dig into the current video's content with the user (full transcript + their question). 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. The one exception is **Research mode** (below): an explicit user pick that ends the loop and opens the current video's content for discussion.
-
-`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_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.
-
-## 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:
-  if out.skipped: FIRST, in output_lang, tell the user one line — "Skipped {out.skipped}:" + a `; `-joined list of `{channel} «{title}» — {reason}` from out.skips (videos the title/content filter dropped on the way here, including your channel directives). Then handle out.status below.
-  out.status:
-    "done"          → sweep finished — tell the user, stop
-    "error"         → setup/config problem (e.g. missing API key) — show `out.error` to the user verbatim, stop
-    "rate_limited"  → YouTube is blocking the egress IP (429 / captcha) — tell the user, stop; recovery in README.md → Proxy
-    "tooling_error" → transcript toolchain failed (proxy down / yt-dlp / network) — tell the user, stop; check proxy health, then 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. B is **unconditional** — it does not depend on there being anything else to write, so an iteration that returns no `skipped` line still opens with the pasted summary, never straight with the tool call. _(If the user says "I don't see the summary" — you skipped B. In Claude Code a PreToolUse gate refuses to record the rating in step D when the pending video's id is missing from your chat text; if it fires, paste the summary, ask for the rating again, then record it.)_
-- **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 three options whose descriptions explain: **OK** = neutral (no effect on the filter), **Weak** = worthless (teach the filter to skip such titles), **Research** = break the loop and dig into this video's content together. The digits never appear in the popup — internally map to `--rating`: **OK → 1, Weak → 0**; Research maps to no digit, it exits the loop (see Research mode). 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 / research channel (no second question): the user types free text. If it equals `stop` (case-insensitive, trimmed) — or the popup is dismissed (✕) — **end the loop**. If it **starts with `?`**, the text after the `?` is a **research question** → Research mode. 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`, not `?…`) → `bun run src/yt-rating.ts --rating <inferred 1|0> --comment "<distilled rule>"`.
-  - **Research** (the option, or a `?…` text) → **break the loop** and switch to **Research mode** below. Skip step E — no more sweep calls this session.
-
-  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.
-
-## Research mode (break the loop and dig in)
-
-The "don't shelve it" path: instead of the briefing landing on a to-do list, the user pulls it apart with you right now — e.g. the channel announces a new tool and the question is whether it beats what their project uses today. Entry: the **Research** option, or an Other text starting with `?`.
-
-1. **Commit first:** `bun run src/yt-rating.ts --rating 1` — engaging with a video is at least neutral, and the bump keeps it from reappearing on the next run. The rating loop is over: no step E, no further sweep calls.
-2. **Get the question.** A `?…` text (or any free text attached to the Research selection) IS the question. If Research was picked bare, ask in `output_lang` what they want to dig into.
-3. **Pull the full transcript** — the summary is too lossy to research from: `bun run src/yt-transcript.ts <videoId> --lang auto`, videoId from `out.pending` (or `data/.cache/pending.json`). The transcript arrives as the tool result — work from it there, never paste it into chat. Non-zero exit (`1` no subtitles / `2` IP-blocked / `3` tooling, reason on stderr) → tell the user and work from the summary instead.
-4. **Work the question with the user, grounded.** The transcript is the source for what the video *claims*; keep "the video claims X" separate from what you verify yourself. Use whatever tools the question needs — read the user's project when they ask "would this fit project xyz", search the web for docs / changelogs / pricing. It is a conversation, not a one-shot report: answer, then iterate until the user is done.
-5. **Closing.** `data/.cache/pending.json` is still on disk, so a verdict can still be recorded: turned out to be hype → `bun run src/yt-rating.ts --rating 0`; a durable channel preference surfaced → `--rating 1 --comment "<distilled rule>"` (the re-bump is a no-op). Mention that `/yt` resumes the queue where it left off — re-enter the rating loop (re-run the engine **bare**) only if the user asks.
-
-## 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 three option **labels** are `OK` / `Weak` / `Research`. Summaries are written in `output_lang` by the content-filter prompt in the engine — not here. Research mode converses in `output_lang` unless the user switches.
-- **Transcripts:** never paste a raw transcript into chat; the summary is the artifact. In research mode, quote only the short passages you need.
-- **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/dist/lib/summary-gate.js

@@ -1,43 +0,0 @@
-/**
- * Decision logic for the /yt summary gate — kept separate from the hook script so it is
- * runtime-agnostic and unit-testable: pure functions over a payload and a transcript.
- *
- * See `src/yt-summary-gate.ts` for why the gate exists and where it had to move to work at all.
- */
-/** Substring identifying the rating writer; the skill always invokes it by this script name. */
-const RATING_SCRIPT = 'yt-rating';
-/**
- * Is this the call that writes a rating? The skill records every rating by running
- * `yt-rating(.ts|.js) --rating <1|0>` through Bash, so the command line is the signal. Anything
- * else — a sweep, a transcript pull, unrelated shell work — is none of the gate's business, and
- * is waved through before this module does any I/O at all.
- */
-export function isRatingWrite(payload) {
-    if (payload.tool_name !== 'Bash')
-        return false;
-    const command = payload.tool_input?.command ?? '';
-    return command.includes(RATING_SCRIPT) && command.includes('--rating');
-}
-/**
- * Did the agent actually paste the summary? The summary carries the video's watch URL, so its id
- * appears verbatim in the pasted text. Only the assistant's own text blocks count: the id also
- * travels through tool calls and their results, and neither is shown to the user.
- */
-export function summaryWasPasted(transcript, videoId) {
-    for (const line of transcript.split('\n')) {
-        if (!line.includes(videoId))
-            continue;
-        let entry;
-        try {
-            entry = JSON.parse(line);
-        }
-        catch {
-            continue;
-        }
-        if (entry.message?.role !== 'assistant' || !Array.isArray(entry.message.content))
-            continue;
-        if (entry.message.content.some((b) => b.type === 'text' && b.text?.includes(videoId)))
-            return true;
-    }
-    return false;
-}

package/dist/yt-summary-gate.js

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/**
- * yt-summary-gate — PreToolUse gate for Claude Code: refuses to RECORD a rating until the
- * video's summary has actually been pasted into the chat.
- *
- * Step B of the rating loop (paste `out.summary` verbatim, THEN ask) is the one instruction the
- * agent can drop with no visible symptom: the popup still appears, the user still answers, and
- * the rating is recorded against a summary nobody saw. A blind rating is worse than no rating:
- * it teaches the title filter from noise.
- *
- * WHY IT GATES THE WRITE AND NOT THE POPUP. Until 0.15.0 this hook ran on `AskUserQuestion` and
- * blocked the popup. That could never work: the harness writes an assistant message's entries to
- * the transcript only once the message is COMPLETE — i.e. after its tool calls have returned —
- * and the skill pastes the summary and opens the popup in a single message. So the gate asked
- * the transcript for text that could not be there yet, and the write it was waiting on could not
- * happen until the gate returned. It blocked every video and cleared on a blind retry (measured
- * 2026-08-30: a marker in a long text block was absent from the transcript during its own
- * message's tool call, and present in the next message immediately). 0.14.2's 5s poll treated
- * that as a timing lag and so only made the block slower.
- *
- * The rating write is a separate Bash call in the FOLLOWING message, by which point the message
- * carrying the summary is closed and on disk — the evidence exists exactly when this hook needs
- * it. The tradeoff is honest: a genuinely skipped paste is now caught after the user has already
- * answered the popup, so that one answer is wasted and the agent has to paste and re-ask. That
- * costs nothing on the happy path, and it guards the thing that actually matters — what gets
- * written into the channel profile.
- *
- * Reads the PreToolUse payload on stdin; exit 0 allows, exit 2 blocks and feeds stderr back to
- * the agent. Anything unexpected — foreign tool, unreadable transcript, no pending video —
- * allows: a gate that misfires on unrelated work would be worse than the bug it guards. This
- * hook is matched on Bash, so it runs on ordinary shell work too: it must decide from the
- * command string and exit before touching the disk.
- */
-import { readFileSync, existsSync } from 'node:fs';
-import { isRatingWrite, summaryWasPasted } from "./lib/summary-gate.js";
-const ALLOW = 0;
-const BLOCK = 2;
-const allow = () => process.exit(ALLOW);
-let payload;
-try {
-    payload = JSON.parse(readFileSync(0, 'utf8'));
-}
-catch {
-    allow();
-}
-if (!isRatingWrite(payload))
-    allow();
-// paths.ts derives the data dir from the cwd, which for a hook is the agent's, not ours — so the
-// import has to wait until we've moved there.
-if (payload.cwd && existsSync(payload.cwd))
-    process.chdir(payload.cwd);
-const { PENDING_FILE } = await import("./lib/paths.js");
-let pending = {};
-try {
-    pending = JSON.parse(readFileSync(PENDING_FILE, 'utf8'));
-}
-catch {
-    allow(); // no pending video (or unreadable) — nothing to gate on
-}
-if (!pending.videoId)
-    allow();
-const transcript = payload.transcript_path;
-if (!transcript || !existsSync(transcript))
-    allow();
-let seen = false;
-try {
-    seen = summaryWasPasted(readFileSync(transcript, 'utf8'), pending.videoId);
-}
-catch {
-    allow();
-}
-if (seen)
-    allow();
-process.stderr.write(`/yt step B not done: the summary for ${pending.videoId} ("${pending.title ?? '?'}") never appeared in your chat text, ` +
-    `so this rating would be recorded against a summary the user never saw.\n` +
-    `Paste out.summary verbatim as your reply, ask for the rating again, then record it.\n`);
-process.exit(BLOCK);