yt-briefing 0.15.1 → 1.1.0

package/dist/lib/llm.js

@@ -1,58 +1,101 @@
 /**
- * Minimal OpenAI-compatible chat client — the only LLM dependency in yt-briefing.
+ * The one LLM call in yt-briefing — a headless Claude Code run (`claude -p`).
  *
- * 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.
+ * There is no API key and no provider to configure: the engine asks the `claude` CLI already
+ * installed and logged in on this machine, so title filtering, summaries and search all run on
+ * the user's Claude Code login (subscription or whatever auth they set up for it).
  *
- * One model does both stages (title classification + summaries). Gemini 2.5 Flash is
- * the default — cheap and fast enough for the batch title filter, capable enough for
- * the summaries.
+ * The run is deliberately bare of everything that makes Claude Code an agent: no tools, no
+ * settings sources (so none of the project's hooks or permissions), no MCP servers, no session
+ * file. It is a single prompt in, a single answer out — the same contract the old
+ * OpenAI-compatible client had.
  *
- * Env (see .env.example) — all required, no defaults:
- *   YT_BRIEFING_LLM_BASE_URL   required (e.g. https://openrouter.ai/api/v1)
- *   YT_BRIEFING_LLM_API_KEY    required
- *   YT_BRIEFING_LLM_MODEL      required (e.g. google/gemini-2.5-flash)
+ * `ANTHROPIC_API_KEY` is removed from the child's environment: when it is set, Claude Code
+ * prefers it over the interactive login, which silently turns every summary into paid API usage
+ * (or a "credit balance too low" failure). The briefing is meant to run on the login.
+ *
+ * Env (all optional):
+ *   YT_BRIEFING_MODEL   model alias or full name passed to `claude --model` (default: sonnet)
+ */
+import { spawn, spawnSync } from 'node:child_process';
+/**
+ * Model alias for every call; one model does both stages. Sonnet: the summary is the product, and a
+ * subscription login does not bill per token, so the default buys quality over speed. Set
+ * YT_BRIEFING_MODEL=haiku for faster, lighter runs.
  */
-import { requireEnv, REQUIRED_LLM } from "./env.js";
+export const DEFAULT_MODEL = 'sonnet';
 export function getModel() {
-    const model = process.env.YT_BRIEFING_LLM_MODEL;
-    if (!model)
-        throw new Error("Missing required environment variable: YT_BRIEFING_LLM_MODEL. Set it in your project root .env.");
-    return model;
+    return process.env.YT_BRIEFING_MODEL || DEFAULT_MODEL;
 }
-export async function chat(prompt, opts = {}) {
-    requireEnv(REQUIRED_LLM);
-    const baseUrl = process.env.YT_BRIEFING_LLM_BASE_URL.replace(/\/+$/, "");
-    const apiKey = process.env.YT_BRIEFING_LLM_API_KEY;
-    const model = opts.model || getModel();
-    const messages = [];
+/** A hung CLI must not hold the sweep forever; a long transcript summary takes well under this. */
+const TIMEOUT_MS = 5 * 60_000;
+/** The child environment: everything but the API key that would override the login. */
+export function childEnv(env = process.env) {
+    const { ANTHROPIC_API_KEY: _drop, ...rest } = env;
+    return rest;
+}
+/** argv for one bare, tool-less, settings-less `claude -p` call. */
+export function claudeArgs(opts = {}) {
+    const args = [
+        '-p',
+        '--model', opts.model || getModel(),
+        '--output-format', 'json',
+        '--tools', '',
+        '--setting-sources', '',
+        '--strict-mcp-config',
+        '--no-session-persistence',
+    ];
     if (opts.system)
-        messages.push({ role: "system", content: opts.system });
-    messages.push({ role: "user", content: prompt });
-    const headers = {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${apiKey}`,
-        "X-Title": "yt-briefing",
-    };
-    const res = await fetch(`${baseUrl}/chat/completions`, {
-        method: "POST",
-        headers,
-        body: JSON.stringify({
-            model,
-            messages,
-            temperature: opts.temperature ?? 0.3,
-        }),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => "");
-        throw new Error(`LLM ${res.status} ${res.statusText}: ${body.slice(0, 300)}`);
+        args.push('--system-prompt', opts.system);
+    return args;
+}
+/** Pull the answer out of `--output-format json`; throws with Claude Code's own error text. */
+export function parseClaudeOutput(stdout) {
+    let data;
+    try {
+        data = JSON.parse(stdout);
     }
-    const data = await res.json();
-    const text = data?.choices?.[0]?.message?.content;
-    if (typeof text !== "string") {
-        throw new Error(`LLM: no content in response: ${JSON.stringify(data).slice(0, 300)}`);
+    catch {
+        throw new Error(`claude: unreadable output: ${stdout.slice(0, 300)}`);
     }
-    return text.trim();
+    if (data.is_error || typeof data.result !== 'string') {
+        throw new Error(`claude: ${String(data.result ?? 'no result').slice(0, 300)}`);
+    }
+    return data.result.trim();
+}
+export async function chat(prompt, opts = {}) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('claude', claudeArgs(opts), { env: childEnv(), stdio: ['pipe', 'pipe', 'pipe'] });
+        let out = '';
+        let err = '';
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`claude: no answer within ${TIMEOUT_MS / 1000}s`));
+        }, TIMEOUT_MS);
+        child.stdout.on('data', (d) => { out += d; });
+        child.stderr.on('data', (d) => { err += d; });
+        child.on('error', (e) => { clearTimeout(timer); reject(new Error(`claude: cannot start (${e.message})`)); });
+        child.on('close', () => {
+            clearTimeout(timer);
+            try {
+                resolve(parseClaudeOutput(out));
+            }
+            catch (e) {
+                reject(out.trim() ? e : new Error(`claude: ${err.trim().slice(0, 300) || 'no output'}`));
+            }
+        });
+        child.stdin.end(prompt);
+    });
+}
+/**
+ * Preflight for the entrypoints: null when the `claude` CLI runs, else a message saying what to
+ * install. Checked once per foreground run, so a missing CLI is a named error instead of every
+ * summary failing (and the title filter silently keeping everything).
+ */
+export function claudeMissing() {
+    const res = spawnSync('claude', ['--version'], { encoding: 'utf8' });
+    if (!res.error && res.status === 0)
+        return null;
+    return 'Claude Code CLI not found: yt-briefing runs its filters and summaries through `claude -p`. ' +
+        'Install Claude Code (https://claude.com/claude-code), log in once, and make sure `claude` is on PATH.';
 }

package/dist/lib/skill-install.js

@@ -1,163 +1,171 @@
 /**
- * skill-install — place this package's SKILL.md files into a coding agent's skills directory.
+ * skill-install — put yt-briefing into a Claude Code project.
  *
  * Shared by the onboarding wizard (`bootstrap.ts`, final step) and the standalone
- * `install-skill.ts` command, so both write the skills identically.
+ * `install-skill.ts` command, so both install identically. Two things land in
+ * `<project>/.claude/skills/`:
  *
- * The package ships TWO skills, each at `.claude/skills/<name>/SKILL.md`:
- *   yt            — the recurring channel briefing loop (sweep + rate).
- *   yt-transcribe — one-shot: a single video's transcript → summary.
- * Both are installed together so an agent gets the whole toolset in one step.
+ *   yt-briefing/   the Claude Code mod (a plugin of function hooks) behind `/yt`: the rating loop
+ *                  as a pane. Claude Code loads a plugin from the project's skills folder by itself
+ *                  (as `yt-briefing@skills-dir`) once the workspace is trusted.
+ *   yt-transcribe/ one-shot skill: a single video's transcript → summary.
+ *   yt-search/     skill: search within one channel → triage → comparison.
  *
- * The shipped SKILL.md files use `bun run src/X.ts` — the dev shortcut: it works when the
- * agent's cwd IS the package folder AND the runtime is Bun (which runs TypeScript directly).
- * That's true for the publisher's own day-to-day use, so it stays the default.
+ * The shipped files use the dev form (`bun run src/X.ts`, or `bun src/X.ts` in the mod): correct
+ * only when the agent's cwd IS the package clone AND the runtime is Bun. For every other install —
+ * a Node user, or the package consumed as a dependency — they are rewritten to a PORTABLE command:
+ * `<runtime> "<project-relative>/dist/X.js"`, the runtime a bare name from PATH and every path
+ * relative to the project root, never machine-absolute. The invariant this rests on is the one the
+ * whole package relies on (paths.ts derives BASE_DIR/DATA_DIR from `process.cwd()` when consumed):
+ * Claude Code runs from the project root. So the installed files survive being committed to git and
+ * shared across machines (a Mac and a Linux VPS). (Requires `dist/` — `bun run build`.)
  *
- * For everyone else — a Node user, or any install whose cwd won't be the package — we rewrite to
- * a PORTABLE command: `<runtime> "<project-relative>/dist/X.js"`. The runtime is the bare name
- * (`node`/`bun`) resolved from PATH, never an absolute binary; the script and `data/` paths are
- * relative to the PROJECT ROOT, never machine-absolute. The invariant this rests on is the same
- * one the whole package already relies on (paths.ts derives BASE_DIR/DATA_DIR from
- * `process.cwd()` when consumed): the agent runs from the project root. So the rewritten skill is
- * machine-independent — it survives being committed to git and shared across machines (e.g. a
- * Mac dev box and a Linux VPS), which an absolute `process.execPath`/`<abs>/dist` baking did not.
- * (Requires `dist/` — build once with `bun run build` / `npm run build`.)
+ * Upgrading from 0.x also removes what 1.0 replaced: the old chat-driven `/yt` skill and the
+ * summary-gate PreToolUse hook in `.claude/settings.json`.
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs';
 import { join, resolve, relative, dirname, sep } from 'node:path';
 import { PKG_ROOT, BASE_DIR, DATA_DIR } from "./paths.js";
-/** Compiled output dir — what a rewritten (dist) skill command points the runtime at. */
+/** Compiled output dir — what a rewritten (dist) command points the runtime at. */
 const DIST_DIR = join(PKG_ROOT, 'dist');
 /** Consumed as a dependency? Then PKG_ROOT lives under node_modules (mirrors paths.ts). */
 const CONSUMED = PKG_ROOT.split(sep).includes('node_modules');
 /**
- * The project root the agent runs from — the cwd against which the rewritten skill's relative
- * paths resolve. When consumed, that's the user's project (parent of `<project>/.yt-briefing`);
- * in a clone it's the package itself. Matches how paths.ts picks BASE_DIR.
+ * The project root Claude Code runs from — the cwd against which the rewritten relative paths
+ * resolve. When consumed, that's the user's project (parent of `<project>/.yt-briefing`); in a
+ * clone it's the package itself. Matches how paths.ts picks BASE_DIR.
  */
 const PROJECT_ROOT = CONSUMED ? dirname(BASE_DIR) : PKG_ROOT;
 /** An absolute path expressed relative to PROJECT_ROOT, with POSIX `/` (portable on Windows too). */
 const toProjectRel = (abs) => relative(PROJECT_ROOT, abs).split(sep).join('/');
 /** The skills this package ships — each lives at `.claude/skills/<name>/SKILL.md`. */
-export const SKILLS = ['yt', 'yt-transcribe', 'yt-search'];
+export const SKILLS = ['yt-transcribe', 'yt-search'];
+/** The mod's folder name under `.claude/skills/` (and its plugin name). */
+export const PLUGIN = 'yt-briefing';
+/** The mod's shipped files, relative to `plugin/`; `hooks/engine.ts` is written, not copied. */
+export const PLUGIN_FILES = [
+    '.claude-plugin/plugin.json',
+    'hooks/hooks.json',
+    'hooks/register.tsx',
+    'types/index.d.ts',
+];
 /** True when the installer itself is running under Bun (vs plain Node). */
 export const isBun = process.versions.bun != null;
 /**
- * The shipped `bun run src/X.ts` command is only correct in ONE situation: the publisher
- * developing *inside the package clone* under Bun (cwd === package, TypeScript runs directly,
- * no build). Everywhere else — and crucially when the package is consumed as a dependency, so
- * the engine lives in node_modules while the user works in their own project — we must bake the
- * compiled `dist/` command instead. This detects that one dev-in-clone case.
+ * The shipped dev commands are only correct in ONE situation: the publisher developing *inside
+ * the package clone* under Bun (cwd === package, TypeScript runs directly, no build). Everywhere
+ * else — crucially when the package is consumed as a dependency — we bake the compiled `dist/`
+ * command instead. This detects that one dev-in-clone case.
  */
 export const isPackageDevCwd = () => isBun && resolve(process.cwd()) === PKG_ROOT;
+/** The Claude Code skills root of a project folder. */
+export const projectSkillsRoot = (projectDir) => join(projectDir, '.claude', 'skills');
 /** Source path of a shipped skill's SKILL.md, by skill name. */
 export const skillSource = (name) => join(PKG_ROOT, '.claude', 'skills', name, 'SKILL.md');
+const runtimeName = () => (isBun ? 'bun' : 'node');
 /**
- * Agent key → display name + the skills ROOT directory it scans (skills install under it).
- *
- * SKILL.md is the cross-agent Agent Skills standard (Anthropic, Dec 2025), now read by 30+
- * tools that each scan their own `<agent-home>/skills/` dir. We only need the right directory
- * per agent — the shipped SKILL.md works unmodified in all of them. The "custom folder" picker
- * option (no AGENTS entry) covers every other compatible agent (Gemini CLI, Copilot, Windsurf…)
- * and defaults to the neutral `.agents/skills/` location.
- */
-export const AGENTS = {
-    '1': { name: 'Claude Code', sub: join('.claude', 'skills') },
-    '2': { name: 'Cursor', sub: join('.cursor', 'skills') },
-    '3': { name: 'Codex', sub: join('.codex', 'skills') },
-};
-/**
- * One shipped skill's SKILL.md. `dist=false` (default) returns it verbatim — the
- * `bun run src/X.ts` dev form, correct only when cwd is the package AND the runtime is Bun.
- * `dist=true` rewrites for the consumed case into PORTABLE, project-relative form: engine
- * commands become `<node|bun> "<rel>/dist/X.js"` (bare runtime from PATH + a path relative to the
- * project root, so they run on any machine from the project cwd), and the bare `data/…` paths the
- * agent reads (e.g. `data/config.json`) become the project-relative DATA_DIR (`.yt-briefing/data/`
- * when consumed). Nothing machine-absolute is baked, so the rewritten skill can be committed and
- * shared across machines. The runtime name follows whoever runs the installer (Node→`node`,
- * Bun→`bun`); the compiled `dist/` build runs under either.
+ * One shipped skill's SKILL.md. `dist=false` returns it verbatim (the dev form). `dist=true`
+ * rewrites engine commands to `<node|bun> "<rel>/dist/X.js"` and the bare `data/…` paths the agent
+ * reads to the project-relative DATA_DIR. Nothing machine-absolute is baked.
  */
 export function skillBody(name, dist = false) {
     const raw = readFileSync(skillSource(name), 'utf8');
     if (!dist)
         return raw;
-    const runtime = isBun ? 'bun' : 'node';
-    const cmd = (base) => `${runtime} "${toProjectRel(join(DIST_DIR, base + '.js'))}"`;
+    const cmd = (base) => `${runtimeName()} "${toProjectRel(join(DIST_DIR, base + '.js'))}"`;
     return raw
-        .replace(/bun run src\/yt-sweep\.ts/g, cmd('yt-sweep'))
-        .replace(/bun run src\/yt-rating\.ts/g, cmd('yt-rating'))
         .replace(/bun run src\/yt-transcript\.ts/g, cmd('yt-transcript'))
         .replace(/bun run src\/yt-search\.ts/g, cmd('yt-search'))
         .replace(/data\//g, toProjectRel(DATA_DIR) + '/');
 }
 /**
- * Write every shipped skill into `root`, each under its own `<name>/SKILL.md` subdir
- * (created if needed). Returns the SKILL.md paths written, in `SKILLS` order.
+ * The mod's `hooks/engine.ts`: how the pane runs the engine. `dist=false` is the shipped dev form;
+ * `dist=true` points at the compiled scripts, relative to the project root (the session's cwd).
  */
-export function installSkills(root, dist = false) {
+export function engineModule(dist = false) {
+    const shipped = readFileSync(join(PKG_ROOT, 'plugin', 'hooks', 'engine.ts'), 'utf8');
+    if (!dist)
+        return shipped;
+    const rel = toProjectRel(DIST_DIR);
+    return [
+        '// How the pane runs the engine, relative to the project root (the session\'s working directory).',
+        '// Written by `yt-briefing install-skill`; re-run it after moving the project or switching runtime.',
+        `export const engine = (name: string): string[] => ['${runtimeName()}', \`${rel}/\${name}.js\`]`,
+        '',
+    ].join('\n');
+}
+/** Write the mod into `<skillsRoot>/yt-briefing/`. Returns the folder written. */
+export function installPlugin(skillsRoot, dist = false) {
+    const dir = join(skillsRoot, PLUGIN);
+    for (const file of PLUGIN_FILES) {
+        const target = join(dir, file);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, readFileSync(join(PKG_ROOT, 'plugin', file), 'utf8'), 'utf8');
+    }
+    writeFileSync(join(dir, 'hooks', 'engine.ts'), engineModule(dist), 'utf8');
+    return dir;
+}
+/** Write every shipped skill into `skillsRoot/<name>/SKILL.md`. Returns the paths written. */
+export function installSkills(skillsRoot, dist = false) {
     return SKILLS.map((name) => {
-        const dir = join(root, name);
+        const dir = join(skillsRoot, name);
         mkdirSync(dir, { recursive: true });
         const target = join(dir, 'SKILL.md');
         writeFileSync(target, skillBody(name, dist), 'utf8');
         return target;
     });
 }
-/** Agent key of Claude Code in AGENTS — the only agent with a PreToolUse hook to gate on. */
-export const CLAUDE_CODE = '1';
-/** Substring identifying our gate inside a settings.json hook command (used to update in place). */
+/** Substring identifying the 0.x summary gate inside a settings.json hook command. */
 const GATE_ID = 'yt-summary-gate';
-/**
- * How settings.json must invoke the gate. Like the skill's engine commands it bakes nothing
- * machine-absolute, but a hook may NOT assume its cwd — Claude Code's hooks reference states the
- * working directory can vary, so a bare relative path would fail open, silently and invisibly
- * (the rating is written ungated, which is exactly the bug the gate exists to catch). Hence the
- * `$CLAUDE_PROJECT_DIR` prefix: still just a placeholder string in the committed JSON, resolved
- * to the project root at hook time.
- */
-export const gateCommand = (dist = false) => dist
-    ? `${isBun ? 'bun' : 'node'} "\${CLAUDE_PROJECT_DIR}/${toProjectRel(join(DIST_DIR, GATE_ID + '.js'))}"`
-    : `bun run src/${GATE_ID}.ts`;
-/**
- * Put the gate into a settings object: a PreToolUse hook on Bash, which is where the rating is
- * written (gating the popup instead cannot work — see src/yt-summary-gate.ts). Merges — every
- * other setting and hook is left as found, and our own entry is updated in place, so
- * reinstalling (or upgrading from the pre-0.15.0 AskUserQuestion matcher) never duplicates or
- * clobbers anything.
- */
-export function withGateHook(settings, command) {
-    const preToolUse = ((settings.hooks ??= {}).PreToolUse ??= []);
-    const mine = preToolUse.find((e) => e.hooks?.some((h) => h.command?.includes(GATE_ID)));
-    const entry = { matcher: 'Bash', hooks: [{ type: 'command', command }] };
-    if (mine)
-        Object.assign(mine, entry);
+/** Drop the 0.x summary gate from a settings object; every other setting and hook stays as found. */
+export function withoutGateHook(settings) {
+    const pre = settings.hooks?.PreToolUse;
+    if (!pre)
+        return settings;
+    const kept = pre.filter((e) => !e.hooks?.some((h) => h.command?.includes(GATE_ID)));
+    if (kept.length === pre.length)
+        return settings;
+    if (kept.length)
+        settings.hooks.PreToolUse = kept;
     else
-        preToolUse.push(entry);
+        delete settings.hooks.PreToolUse;
+    if (settings.hooks && Object.keys(settings.hooks).length === 0)
+        delete settings.hooks;
     return settings;
 }
 /**
- * Register the gate in a Claude Code project's `.claude/settings.json`.
- *
- * Returns the settings path written, or null when the file exists but isn't parseable JSON: a
- * hand-edited config is not ours to rewrite, so the caller tells the user to add it by hand.
+ * Remove what 1.0 replaced from a project: the chat-driven `/yt` skill (only if it is ours — it
+ * runs yt-sweep) and the summary gate in `.claude/settings.json` (left alone if the file isn't
+ * valid JSON: a hand-edited config is not ours to rewrite). Returns what was removed.
  */
-export function installClaudeGate(projectDir, dist = false) {
-    const target = join(projectDir, '.claude', 'settings.json');
-    let settings = {};
-    if (existsSync(target)) {
+export function removeLegacy(projectDir) {
+    const removed = [];
+    const oldSkill = join(projectSkillsRoot(projectDir), 'yt');
+    const oldSkillMd = join(oldSkill, 'SKILL.md');
+    if (existsSync(oldSkillMd) && readFileSync(oldSkillMd, 'utf8').includes('yt-sweep')) {
+        rmSync(oldSkillMd);
+        if (readdirSync(oldSkill).length === 0)
+            rmSync(oldSkill, { recursive: true });
+        removed.push(oldSkillMd);
+    }
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (existsSync(settingsPath)) {
         try {
-            settings = JSON.parse(readFileSync(target, 'utf8'));
-        }
-        catch {
-            return null;
+            const before = readFileSync(settingsPath, 'utf8');
+            const after = JSON.stringify(withoutGateHook(JSON.parse(before)), null, 2) + '\n';
+            if (JSON.stringify(JSON.parse(before)) !== JSON.stringify(JSON.parse(after))) {
+                writeFileSync(settingsPath, after, 'utf8');
+                removed.push(`${settingsPath} (summary gate hook)`);
+            }
         }
+        catch { /* not valid JSON → leave it */ }
     }
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, JSON.stringify(withGateHook(settings, gateCommand(dist)), null, 2) + '\n', 'utf8');
-    return target;
+    return removed;
+}
+/** Install everything into a project: legacy cleanup, the mod, the skills. Returns paths written/removed. */
+export function installAll(projectDir, dist) {
+    const removed = removeLegacy(projectDir);
+    const root = projectSkillsRoot(projectDir);
+    const written = [installPlugin(root, dist), ...installSkills(root, dist)];
+    return { written, removed };
 }
-/** The agent's skills ROOT inside a project folder (the project you open in the agent). */
-export const projectSkillsRoot = (agentKey, projectDir) => join(projectDir, AGENTS[agentKey].sub);
-/** Suggested target for a "custom" (any other agent) install — the open `.agents` convention,
- *  rooted at the user's current project (not the package, which may be in node_modules). */
-export const customSkillsRootDefault = () => join(process.cwd(), '.agents', 'skills');

package/dist/yt-rating.js

@@ -2,6 +2,7 @@
 /**
  * Usage:
  *   bun src/yt-rating.ts --rating 0|1 [--comment "..."]
+ *   bun src/yt-rating.ts --raw-comment "..." [--rating 0|1]
  *
  * Channel / id / title / type default to <DATA_DIR>/.cache/pending.json (written by
  * yt-sweep.ts) so the agent only passes --rating (+ optional --comment) — no fragile
@@ -12,12 +13,20 @@
  *   1 = neutral      → bump the state pointer only (video seen, no signal), profile untouched.
  *   0 = worthless    → append a negative few-shot to `## Skip titles` (FIFO cap, default 10).
  *   comment          → append a durable rule to `## Notes`, seen by both filters.
+ *   raw comment      → the user's words as typed: distilled into a rule (and, unless --rating is
+ *                      given, the rating it implies) through `claude -p`, then stored as above.
+ *
+ * After a recorded rating, `after_rate` from config.json (if set) runs detached from the project
+ * root — e.g. a script that commits DATA_DIR. The engine never runs VCS itself.
  *
  * Direct durable commit — no rolling buffer, no consolidation. Idempotent: identical
  * bullets are de-duplicated; a state.md re-bump is a no-op.
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { spawn } from 'node:child_process';
 import { loadEnv } from "./lib/env.js";
+import { loadConfig } from "./lib/config.js";
+import { distillComment } from "./lib/distill.js";
 import { parseChannels, appendSkipTitle, appendNote, bumpStatePointer } from "./lib/yt-lib.js";
 import { CHANNELS_MD, STATE_MD, PENDING_FILE, QUEUE_FILE, profilePath } from "./lib/paths.js";
 loadEnv();
@@ -47,25 +56,26 @@ function parseArgs(argv) {
     const type = getArg(argv, '--type') ?? pending.type ?? null;
     const ratingRaw = getArg(argv, '--rating');
     const comment = getArg(argv, '--comment') ?? '';
+    const rawComment = (getArg(argv, '--raw-comment') ?? '').trim();
     const baseline = argv.includes('--baseline') || pending.is_baseline === true;
     const noState = argv.includes('--no-state');
     const capRaw = getArg(argv, '--cap');
-    if (!channel || !id || !title || !type || !ratingRaw) {
-        console.error('Usage: yt-briefing rate --rating 0|1 [--comment "..."]  (channel/id/title/type default to .cache/pending.json; override with --channel @X --id Y --title "..." --type longform|short|live) [--baseline] [--cap 10] [--no-state]');
+    if (!channel || !id || !title || !type || (!ratingRaw && !rawComment)) {
+        console.error('Usage: yt-briefing rate --rating 0|1 [--comment "..."] | --raw-comment "..." [--rating 0|1]  (channel/id/title/type default to .cache/pending.json; override with --channel @X --id Y --title "..." --type longform|short|live) [--baseline] [--cap 10] [--no-state]');
         process.exit(1);
     }
     if (!['longform', 'short', 'live'].includes(type)) {
         console.error(`Invalid --type: ${type}`);
         process.exit(1);
     }
-    const rating = parseInt(ratingRaw, 10);
+    const rating = ratingRaw === null ? null : parseInt(ratingRaw, 10);
     // Permissive 0..5 so older profiles / scripts keep working; the live UI emits only 0|1.
-    if (!Number.isFinite(rating) || rating < 0 || rating > 5) {
+    if (rating !== null && (!Number.isFinite(rating) || rating < 0 || rating > 5)) {
         console.error(`Invalid --rating: ${ratingRaw} (must be 0 or 1)`);
         process.exit(1);
     }
     const cap = capRaw ? parseInt(capRaw, 10) : 10;
-    return { channel, id, title, type: type, rating, comment, baseline, cap, noState };
+    return { channel, id, title, type: type, rating, comment, rawComment, baseline, cap, noState };
 }
 const args = parseArgs(process.argv.slice(2));
 const channels = parseChannels(readFileSync(CHANNELS_MD, 'utf8'));
@@ -80,15 +90,31 @@ if (!existsSync(profile)) {
     process.exit(1);
 }
 const date = new Date().toISOString().slice(0, 10);
+// 0. A raw comment becomes a rule (+ the implied rating unless one was given explicitly).
+let rule = args.comment.trim();
+let rating = args.rating;
+if (args.rawComment) {
+    try {
+        const d = await distillComment(args.rawComment, { channel: args.channel, title: args.title, type: args.type });
+        rule = d.rule;
+        rating ??= d.rating;
+    }
+    catch (e) {
+        console.error(`Comment not recorded: ${e.message}`);
+        process.exit(1);
+    }
+}
+if (rating === null)
+    rating = 1;
 // 1. Durable profile writes (no buffer, no consolidation):
 //    rating=0 → negative few-shot; comment → Notes rule. rating=1 w/o comment → nothing.
 const profileBefore = readFileSync(profile, 'utf8');
 let profileAfter = profileBefore;
-if (args.rating === 0) {
+if (rating === 0) {
     profileAfter = appendSkipTitle(profileAfter, { title: args.title, type: args.type }, args.cap);
 }
-if (args.comment && args.comment.trim()) {
-    profileAfter = appendNote(profileAfter, args.comment.trim());
+if (rule) {
+    profileAfter = appendNote(profileAfter, rule);
 }
 if (profileAfter !== profileBefore) {
     writeFileSync(profile, profileAfter, 'utf8');
@@ -117,8 +143,16 @@ if (!args.noState && existsSync(QUEUE_FILE)) {
     }
     catch { /* corrupt / foreign queue → ignore; the next sweep rebuilds it */ }
 }
+// 4. The user's after-rate command (e.g. commit DATA_DIR to git). Detached: the rating is already
+//    durable on disk, so a slow or failing command must not hold or fail the rating.
+const afterRate = loadConfig().after_rate;
+if (afterRate) {
+    spawn(afterRate, { shell: true, detached: true, stdio: 'ignore' }).unref();
+}
 console.log(JSON.stringify({
     ok: true,
     profile: `channels/${ch.slug}.md`,
+    rating,
+    ...(rule ? { rule } : {}),
     state_bumped: stateBumped,
 }));

package/dist/yt-search.js

@@ -35,8 +35,8 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_LLM, REQUIRED_YOUTUBE } from "./lib/env.js";
-import { chat, getModel } from "./lib/llm.js";
+import { loadEnv, missingEnv, missingEnvMessage, REQUIRED_YOUTUBE } from "./lib/env.js";
+import { chat, claudeMissing } from "./lib/llm.js";
 import { outputLang } from "./lib/config.js";
 import { fetchChannelVideos } from "./lib/yt-api.js";
 import { normalizeHandle } from "./lib/channels.js";
@@ -135,7 +135,7 @@ Output ONLY a raw JSON array, best first, no fences:
 [{"id":"VIDEO_ID","keep":true,"score":0-100,"reason":"max 12 words"},...]
 Set keep=false for anything not relevant to the intent.`;
     try {
-        const out = await chat(prompt, { system: 'You output ONLY a raw JSON array as instructed.', temperature: 0 });
+        const out = await chat(prompt, { system: 'You output ONLY a raw JSON array as instructed.' });
         const arr = parseJsonArray(out);
         if (!arr)
             return [];
@@ -194,7 +194,6 @@ Language: natural ${LANG}; foreign words only for proper nouns or established te
 Output ONLY the summary OR 'OFFTOPIC: <reason>'. No preamble.`;
     return chat(prompt, {
         system: `You are a research-grade video summarizer writing in ${LANG}. Output only the summary or 'OFFTOPIC: <reason>'.`,
-        model: getModel(),
     });
 }
 /** Synthesize a comparison across everything kept. */
@@ -211,7 +210,7 @@ Write:
 - A final recommendation with the reasoning, and who it's for.
 
 Language: natural ${LANG}; foreign words only for proper nouns or established technical terms. Cite videos as [1], [2]… matching the order above. Output only the comparison.`;
-    return chat(prompt, { system: `You synthesize a decision-grade comparison in ${LANG}. No preamble.`, model: getModel() });
+    return chat(prompt, { system: `You synthesize a decision-grade comparison in ${LANG}. No preamble.` });
 }
 /** Lazy yield: advance to the next candidate that has a transcript, summarize, emit. */
 async function yieldNext(queue) {
@@ -242,13 +241,13 @@ async function yieldNext(queue) {
     emit({ status: 'done', kept: loadKept().length });
 }
 async function main() {
-    // LLM is needed on every path (rerank, summaries, compare). Fail fast naming any missing var
+    // The `claude` CLI is needed on every path (rerank, summaries, compare). Fail fast if it's missing
     // (the throw is turned into a status:"error" by the .catch below). YouTube is checked separately,
     // only when building a fresh queue (the compare/keep/skip paths work off cache, no API).
     {
-        const missing = missingEnv(REQUIRED_LLM);
-        if (missing.length)
-            emit({ status: 'error', error: missingEnvMessage(missing) });
+        const noClaude = claudeMissing();
+        if (noClaude)
+            emit({ status: 'error', error: noClaude });
     }
     // --compare: synthesize from kept summaries.
     if (COMPARE) {