atris 3.56.0 → 3.56.1

package/commands/youtube.js

@@ -1,5 +1,6 @@
 const { apiRequestJson } = require('../utils/api');
 const { ensureBilledCommandAuth } = require('./auth');
+const applyGate = require('../lib/apply-gate');
 const { spawnSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
@@ -28,7 +29,9 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
   output(`Usage: ${commandName} search "<query>" [--limit N] [--json]`);
   output(`       ${commandName} search --paid "<query>" [--limit N] [--json]`);
-  output(`       ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine]`);
+  output(`       ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine] [--save]`);
+  output(`       ${commandName} teach <youtube-url> [--section N] [--save]`);
+  output(`       ${commandName} unsave <url-or-id>`);
   output(`       ${commandName} process <youtube-url> [options]`);
   output(`       ${commandName} digest [--days N]`);
   output(`       ${commandName} watch add <channel-url-or-@handle>`);
@@ -39,8 +42,9 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('');
   output('search = free local discovery (ytsearch / yt-dlp), returns youtu.be links');
   output('search --paid = 5 credits, watch permalinks + titles from Atris');
-  output('notes = free local notes for one url, several urls, or a playlist');
-  output('process = 5 credits cloud knowledge');
+  output('notes = free local notes to stdout; ephemeral unless --save');
+  output('teach = one chapter from local captions; ephemeral unless --save');
+  output('process = 5 credits cloud knowledge (needs a filled Apply)');
   output('digest = one decision page from this week\'s video briefs');
   output('watch = subscribed channels turn into briefs without a human');
   output('Process a YouTube video through Atris using timestamped transcript-first analysis.');
@@ -49,6 +53,9 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('Options:');
   output('  --limit <n>         Max search results (default: 5)');
   output('  --paid              Bill 5 credits for watch permalinks (search only)');
+  output('  --save              File brief, journal line, and apply stub (notes and teach)');
+  output('  --section <n>       Chapter to teach, 1-based (teach only, default: 1)');
+  output('  --unsave            Delete filed brief and apply stub (no paid calls)');
   output('  --query, -q <text>  Focus question for the analysis');
   output('  --agent <id>        Agent id to store knowledge against');
   output('  --store             Save as agent knowledge (requires --agent)');
@@ -64,6 +71,11 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`  ${commandName} search "MCP agents" --limit 10`);
   output(`  ${commandName} search --paid "MCP agents 2026"`);
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID`);
+  output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID --save`);
+  output(`  ${commandName} teach "https://www.youtube.com/watch?v=VIDEO_ID"`);
+  output(`  ${commandName} teach "https://www.youtube.com/watch?v=VIDEO_ID" --section 2`);
+  output(`  ${commandName} notes --unsave VIDEO_ID`);
+  output(`  ${commandName} unsave VIDEO_ID`);
   output(`  ${commandName} notes https://www.youtube.com/watch?v=VIDEO_ID https://youtu.be/OTHER_ID`);
   output(`  ${commandName} notes https://www.youtube.com/playlist?list=PLAYLIST_ID`);
   output(`  ${commandName} https://www.youtube.com/watch?v=VIDEO_ID`);
@@ -300,14 +312,14 @@ function fetchCaptionText(urlString, redirects = 0) {
   });
 }
 
-function parseCaptionText(raw) {
+function parseCaptionCues(raw) {
   const trimmed = String(raw || '').trimStart();
-  if (!trimmed) return '';
+  if (!trimmed) return [];
 
   if (trimmed.startsWith('{')) {
     try {
       const payload = JSON.parse(trimmed);
-      const segments = [];
+      const cues = [];
       for (const event of payload.events || []) {
         const text = (event.segs || [])
           .map((piece) => piece.utf8 || '')
@@ -315,18 +327,21 @@ function parseCaptionText(raw) {
           .replace(/\s+/g, ' ')
           .trim();
         if (!text) continue;
-        const line = timestampedCaptionLine(text, Number(event.tStartMs));
-        if (segments[segments.length - 1] === line) continue;
-        segments.push(line);
+        const startMs = Number(event.tStartMs);
+        const cue = { startMs: Number.isFinite(startMs) ? startMs : 0, text };
+        if (cues.length && cues[cues.length - 1].text === cue.text && cues[cues.length - 1].startMs === cue.startMs) {
+          continue;
+        }
+        cues.push(cue);
       }
-      return segments.join('\n');
+      return cues;
     } catch {
-      return '';
+      return [];
     }
   }
 
   if (/^WEBVTT/i.test(trimmed) || trimmed.includes('-->')) {
-    const segments = [];
+    const cues = [];
     for (const block of String(raw).split(/\r?\n\r?\n+/)) {
       const lines = block.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
       const timeLine = lines.find((line) => line.includes('-->'));
@@ -339,7 +354,28 @@ function parseCaptionText(raw) {
         .filter((line, index, all) => index === 0 || line !== all[index - 1])
         .join(' ')
         .trim();
-      const captionLine = timestampedCaptionLine(text, startMs);
+      if (!text) continue;
+      const cue = { startMs: startMs == null ? 0 : startMs, text };
+      if (cues.length && cues[cues.length - 1].text === cue.text && cues[cues.length - 1].startMs === cue.startMs) {
+        continue;
+      }
+      cues.push(cue);
+    }
+    return cues;
+  }
+
+  return [];
+}
+
+function parseCaptionText(raw) {
+  const trimmed = String(raw || '').trimStart();
+  if (!trimmed) return '';
+
+  const cues = parseCaptionCues(raw);
+  if (cues.length) {
+    const segments = [];
+    for (const cue of cues) {
+      const captionLine = timestampedCaptionLine(cue.text, cue.startMs);
       if (!captionLine || segments[segments.length - 1] === captionLine) continue;
       segments.push(captionLine);
     }
@@ -393,6 +429,19 @@ async function extractLocalTranscript(youtubeUrl, deps = {}) {
 }
 
 async function processYoutube(options, deps = {}) {
+  const applyStatus = (deps.ensureProcessApply || ensureProcessApply)({
+    cwd: deps.cwd || process.cwd(),
+    url: options.youtubeUrl,
+    now: deps.now,
+    output: deps.output,
+  });
+  if (applyStatus !== 0) {
+    const err = new Error(PROCESS_APPLY_MESSAGE);
+    err.exitCode = applyStatus;
+    err.applyRequired = true;
+    throw err;
+  }
+
   const apiFn = deps.apiRequestJson || apiRequestJson;
   const ensureBilled = deps.ensureBilledCommandAuth || ensureBilledCommandAuth;
   let auth = await ensureBilled('youtube', deps);
@@ -490,6 +539,14 @@ function videoIdFromUrl(url) {
   return short ? short[1] : null;
 }
 
+function videoIdFromArg(arg) {
+  const fromUrl = videoIdFromUrl(arg);
+  if (fromUrl) return fromUrl;
+  const text = String(arg || '').trim();
+  if (/^[A-Za-z0-9_-]{6,}$/.test(text)) return text;
+  return null;
+}
+
 function looksLikeYoutubeUrl(arg) {
   const text = String(arg || '').trim();
   if (!text || text.startsWith('-')) return false;
@@ -505,17 +562,24 @@ function parseNotesArgs(argv = []) {
   const urls = [];
   let engine = null;
   let help = false;
+  let save = false;
+  let unsave = false;
   for (const raw of argv) {
     const arg = String(raw);
-    if (arg === '--help' || arg === '-h' || arg === 'help') {
-      help = true;
-      continue;
-    }
+    if (arg === '--help' || arg === '-h' || arg === 'help') help = true;
+    else if (arg === '--save') save = true;
+    else if (arg === '--unsave') unsave = true;
+  }
+  for (const raw of argv) {
+    const arg = String(raw);
+    if (arg === '--help' || arg === '-h' || arg === 'help') continue;
+    if (arg === '--save' || arg === '--unsave') continue;
     if (arg.startsWith('-')) continue;
     if (looksLikeYoutubeUrl(arg)) urls.push(arg);
+    else if (unsave && videoIdFromArg(arg)) urls.push(arg);
     else engine = arg;
   }
-  return { urls, engine, help };
+  return { urls, engine, help, save, unsave };
 }
 
 function dateStamp(now) {
@@ -572,6 +636,94 @@ function fileBriefFromNotes({ cwd, url, workDir, now } = {}) {
   }
 }
 
+const APPLY_NEXT_MESSAGE =
+  'next: write one apply (change + receipt) before process.';
+const PROCESS_APPLY_MESSAGE =
+  'write one apply (change + receipt) before process.';
+
+function applySidecarRel(id) {
+  return applyGate.applySidecarRel('youtube', id);
+}
+
+function ensureNotesApply({ cwd, url, now, output } = {}) {
+  const id = videoIdFromUrl(url);
+  return applyGate.ensureApply({
+    cwd,
+    source: url,
+    rel: id ? applySidecarRel(id) : null,
+    now,
+    output,
+    incompleteMessage: APPLY_NEXT_MESSAGE,
+    required: false,
+  });
+}
+
+function youtubeBriefRel(id) {
+  return `atris/wiki/briefs/youtube-${id}.md`;
+}
+
+function unsaveYoutubeNotes(target, deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const cwd = deps.cwd || process.cwd();
+  const id = videoIdFromArg(target);
+  if (!id) {
+    output('usage: atris youtube unsave <url-or-id>');
+    return 2;
+  }
+  const briefRel = youtubeBriefRel(id);
+  const applyRel = applySidecarRel(id);
+  const removed = [];
+  for (const rel of [briefRel, applyRel]) {
+    const abs = path.join(cwd, rel);
+    try {
+      if (fs.existsSync(abs)) {
+        fs.unlinkSync(abs);
+        removed.push(rel);
+      }
+    } catch {
+      // already gone or unreadable: do not error
+    }
+  }
+  if (!removed.length) {
+    output(`already gone: ${briefRel} and ${applyRel}`);
+    return 0;
+  }
+  output(`removed ${removed.join(' and ')}`);
+  return 0;
+}
+
+function runYoutubeUnsave(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  const parsed = parseNotesArgs(['--unsave', ...args]);
+  if (parsed.help) {
+    showYoutubeHelp(output, deps.commandName || 'atris youtube');
+    return 0;
+  }
+  if (!parsed.urls.length) {
+    output('usage: atris youtube unsave <url-or-id>');
+    return 2;
+  }
+  let code = 0;
+  for (const target of parsed.urls) {
+    const status = unsaveYoutubeNotes(target, deps);
+    if (status !== 0) code = status;
+  }
+  return code;
+}
+
+function ensureProcessApply({ cwd, url, now, output } = {}) {
+  const id = videoIdFromUrl(url);
+  return applyGate.ensureApply({
+    cwd,
+    source: url,
+    rel: id ? applySidecarRel(id) : null,
+    now,
+    output,
+    incompleteMessage: PROCESS_APPLY_MESSAGE,
+    required: true,
+  });
+}
+
 const DIGEST_ENGINE_TIMEOUT_MS = 240000;
 const DEFAULT_DIGEST_DAYS = 7;
 
@@ -1187,7 +1339,7 @@ function runOneNotesItem(item, engine, deps = {}) {
   } catch {
     status = 1;
   }
-  const brief = status === 0 ? fileNotesBrief(item.url, deps) : null;
+  const brief = status === 0 && deps.save ? fileNotesBrief(item.url, deps) : null;
   const seconds = Math.max(0, Math.round((readNowMs(deps) - started) / 1000));
   const ok = status === 0;
   output(`${label}  ${seconds}s  ${ok ? (brief || 'ok') : 'FAILED'}`);
@@ -1203,7 +1355,8 @@ function formatNotesSummary(rows = []) {
   return lines.join('\n');
 }
 
-function runYoutubeNotesBatch({ urls, engine } = {}, deps = {}) {
+function runYoutubeNotesBatch({ urls, engine, save } = {}, deps = {}) {
+  deps = { ...deps, save: save === true || deps.save === true };
   const output = deps.output || ((line = '') => console.error(line));
   const items = expandNotesTargets(urls || [], deps);
   const rows = [];
@@ -1226,8 +1379,16 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
     return 1;
   }
   const status = readRunnerStatus(result);
-  if (status === 0) fileNotesBrief(url, deps);
-  return status;
+  if (status !== 0) return status;
+  if (!deps.save) return 0;
+  fileNotesBrief(url, deps);
+  const ensureApply = deps.ensureApply || ensureNotesApply;
+  return ensureApply({
+    cwd: deps.cwd || process.cwd(),
+    url,
+    now: deps.now,
+    output: deps.output,
+  });
 }
 
 function runYoutubeNotes(args = [], deps = {}) {
@@ -1237,15 +1398,19 @@ function runYoutubeNotes(args = [], deps = {}) {
     showYoutubeHelp(output, deps.commandName || 'atris youtube');
     return 0;
   }
+  if (parsed.unsave) {
+    return runYoutubeUnsave(args, deps);
+  }
   if (!parsed.urls.length) {
     output(YTNOTES_USAGE);
     output(YTNOTES_HINT);
     return 2;
   }
+  const nextDeps = { ...deps, save: parsed.save };
   if (parsed.urls.length === 1 && !isPlaylistUrl(parsed.urls[0])) {
-    return runSingleYoutubeNotes(parsed.urls[0], parsed.engine, deps);
+    return runSingleYoutubeNotes(parsed.urls[0], parsed.engine, nextDeps);
   }
-  return runYoutubeNotesBatch(parsed, deps);
+  return runYoutubeNotesBatch(parsed, nextDeps);
 }
 
 const DEFAULT_SEARCH_LIMIT = 5;
@@ -1261,6 +1426,8 @@ const LOCAL_SEARCH_CACHE_TTL_MS = 60 * 60 * 1000;
 const LOCAL_SEARCH_CACHE_FILE = 'youtube-search-cache.json';
 const LOCAL_SEARCH_CACHE_NOTE =
   'cached because youtube rate-limited local search.';
+const PAID_SEARCH_FRESH_CACHE_REFUSE =
+  'free cache still has results for this query. drop --paid or wait until the cache expires.';
 
 function showYoutubeSearchHelp(output = console.log, commandName = 'atris youtube') {
   output('');
@@ -1489,24 +1656,50 @@ function paidSearchVideos(data) {
   return rows;
 }
 
-function creditsLine(data) {
-  const payload = unwrapSearchPayload(data);
-  const used = data?.credits_used !== undefined ? data.credits_used : payload.credits_used;
-  const remaining = data?.credits_remaining !== undefined
+function paidSearchCredits(data) {
+  if (!data || typeof data !== 'object') {
+    return { used: undefined, remaining: undefined, refunded: undefined };
+  }
+  const payload = unwrapSearchPayload(data) || {};
+  const used = data.credits_used !== undefined ? data.credits_used : payload.credits_used;
+  const remaining = data.credits_remaining !== undefined
     ? data.credits_remaining
     : payload.credits_remaining;
-  if (used === undefined && remaining === undefined) return '';
-  return `Credits: ${used !== undefined ? used : '?'} used, ${remaining !== undefined ? remaining : '?'} remaining`;
+  let refunded = data.credits_refunded !== undefined
+    ? data.credits_refunded
+    : payload.credits_refunded;
+  if (refunded === undefined && (data.refunded === true || payload.refunded === true)) {
+    refunded = true;
+  }
+  return { used, remaining, refunded };
+}
+
+function creditsWereRefunded(credits) {
+  if (!credits) return false;
+  if (credits.used === 0) return true;
+  if (credits.refunded === true) return true;
+  return typeof credits.refunded === 'number' && credits.refunded > 0;
+}
+
+function formatCreditsLines(credits) {
+  const lines = [];
+  if (credits.used !== undefined || credits.remaining !== undefined) {
+    lines.push(`Credits: ${credits.used !== undefined ? credits.used : '?'} used, ${credits.remaining !== undefined ? credits.remaining : '?'} remaining`);
+  }
+  if (creditsWereRefunded(credits)) {
+    lines.push('credits refunded');
+  }
+  return lines;
 }
 
 function formatPaidSearchResults(data) {
   const lines = paidSearchVideos(data).map((row) => (
     row.title ? `${row.title} | ${row.url}` : row.url
   ));
-  const credits = creditsLine(data);
-  if (credits) {
+  const creditLines = formatCreditsLines(paidSearchCredits(data));
+  if (creditLines.length) {
     if (lines.length) lines.push('');
-    lines.push(credits);
+    lines.push(...creditLines);
   }
   return lines.join('\n');
 }
@@ -1519,7 +1712,13 @@ function youtubeSearchFailureError(result) {
       : result.status === 502
         ? ' YouTube search is unavailable; retry in a few seconds.'
         : '';
-  return new Error(`YouTube search failed (${result.status}): ${resultErrorText(result)}.${hint}`);
+  const credits = paidSearchCredits(result.data);
+  const refundHint = result.status === 502 && creditsWereRefunded(credits)
+    ? ' credits refunded.'
+    : '';
+  const lines = [`YouTube search failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
+  lines.push(...formatCreditsLines(credits));
+  return new Error(lines.join('\n'));
 }
 
 async function requestPaidYoutubeSearch(options, deps = {}) {
@@ -1556,6 +1755,10 @@ async function requestPaidYoutubeSearch(options, deps = {}) {
 
 async function runPaidYoutubeSearch(options, deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
+  if (readFreshLocalSearchCache(options.query, deps)) {
+    output(PAID_SEARCH_FRESH_CACHE_REFUSE);
+    return 2;
+  }
   const data = await requestPaidYoutubeSearch(options, deps);
   if (options.json) {
     output(JSON.stringify(data, null, 2));
@@ -1733,6 +1936,384 @@ async function runYoutubeSearch(args = [], deps = {}) {
   return 0;
 }
 
+const YTTEACH_USAGE = 'usage: atris youtube teach <youtube-url> [--section N] [--save]';
+const TEACH_PAID_REFUSE = 'teach is free local captions. drop --paid.';
+const TEACH_APPLY_NEXT_MESSAGE = APPLY_NEXT_MESSAGE;
+const MECHANISM_STOP = new Set([
+  'the', 'this', 'that', 'and', 'but', 'for', 'with', 'from', 'you', 'we', 'they',
+  'what', 'when', 'how', 'why', 'there', 'here', 'then', 'just', 'also', 'very',
+  'really', 'about', 'into', 'over', 'after', 'before', 'because', 'while', 'where',
+  'which', 'their', 'your', 'our', 'its', 'not', 'all', 'any', 'some', 'more', 'most',
+  'other', 'first', 'second', 'next', 'last', 'new', 'old', 'good', 'bad', 'big',
+  'small', 'long', 'short', 'video', 'chapter', 'section', 'youtube', 'transcript',
+  'yeah', 'okay', 'ok', 'so', 'well', 'like', 'right', 'now', 'one', 'two',
+  'who', 'every', 'holy', 'want', 'operating',
+]);
+const NUMBER_UNITS = 'percent|million|billion|thousand|people|hours?|minutes?|seconds?|years?|months?|weeks?|days?|cycles?';
+const NUMBER_CLAIM_VERBS = 'install|ship|hire|raise|cut|save|cost|last|weigh|span|spend';
+const MECHANISM_HEADS = 'window|model|principle|pattern|loop|cycle|method|rule|doctrine|framework|heuristic';
+const TEACH_SWEAR_RE = /\b(fuck(?:ing)?|shit|damn|ass|bitch|crap)\b/i;
+const GENERIC_MECHANISM_LEFT = new Set([
+  ...MECHANISM_STOP,
+  'a', 'an', 'in', 'of', 'to', 'my', 'i', 'im', "i'm",
+]);
+
+function parseTeachArgs(argv = []) {
+  const args = [...argv];
+  const options = {
+    help: false,
+    save: false,
+    url: null,
+    section: 1,
+  };
+
+  if (args.length === 0 || ['help', '--help', '-h'].includes(args[0])) {
+    options.help = true;
+    return options;
+  }
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = String(args[i]);
+    if (arg === '--help' || arg === '-h' || arg === 'help') {
+      options.help = true;
+    } else if (arg === '--save') {
+      options.save = true;
+    } else if (arg === '--paid') {
+      throw new Error(TEACH_PAID_REFUSE);
+    } else if (arg === '--section') {
+      const raw = args[i + 1];
+      const value = Number.parseInt(raw, 10);
+      if (raw == null || String(raw).startsWith('--') || !Number.isInteger(value) || value < 1) {
+        throw new Error('--section must be a positive integer');
+      }
+      options.section = value;
+      i += 1;
+    } else if (arg.startsWith('--section=')) {
+      const value = Number.parseInt(arg.slice('--section='.length), 10);
+      if (!Number.isInteger(value) || value < 1) {
+        throw new Error('--section must be a positive integer');
+      }
+      options.section = value;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`);
+    } else if (!options.url && looksLikeYoutubeUrl(arg)) {
+      options.url = arg;
+    } else {
+      throw new Error(`Unexpected argument: ${arg}`);
+    }
+  }
+
+  if (options.help) return options;
+  if (!options.url) throw new Error('Missing YouTube URL. Run "atris youtube teach --help".');
+  return options;
+}
+
+function chapterStartSeconds(chapter) {
+  if (!chapter) return NaN;
+  if (chapter.startSeconds != null) return Number(chapter.startSeconds);
+  return Number(chapter.start_time);
+}
+
+function chapterEndSeconds(chapter) {
+  if (!chapter) return NaN;
+  if (chapter.endSeconds != null) return Number(chapter.endSeconds);
+  return Number(chapter.end_time);
+}
+
+function normalizeChapters(rawChapters, durationSeconds) {
+  const duration = Number(durationSeconds) || 0;
+  const list = Array.isArray(rawChapters) ? rawChapters.filter(Boolean) : [];
+  if (!list.length) {
+    return [{
+      index: 1,
+      title: 'full video',
+      startSeconds: 0,
+      endSeconds: duration || Infinity,
+    }];
+  }
+  return list.map((chapter, index) => {
+    const start = chapterStartSeconds(chapter);
+    const startSeconds = Number.isFinite(start) ? start : 0;
+    const nextStart = chapterStartSeconds(list[index + 1]);
+    const explicitEnd = chapterEndSeconds(chapter);
+    const endSeconds = Number.isFinite(explicitEnd)
+      ? explicitEnd
+      : (Number.isFinite(nextStart) ? nextStart : (duration || Infinity));
+    const title = String(chapter.title || `section ${index + 1}`).trim() || `section ${index + 1}`;
+    return { index: index + 1, title, startSeconds, endSeconds };
+  });
+}
+
+function sliceCuesForChapter(cues = [], chapter) {
+  if (!chapter) return [];
+  const startMs = Number(chapter.startSeconds) * 1000;
+  const endMs = Number(chapter.endSeconds) * 1000;
+  return (cues || []).filter((cue) => {
+    const at = Number(cue.startMs);
+    if (!Number.isFinite(at)) return false;
+    if (!Number.isFinite(startMs)) return true;
+    if (at < startMs) return false;
+    if (Number.isFinite(endMs) && at >= endMs) return false;
+    return true;
+  });
+}
+
+function teachCaptionWords(text) {
+  return String(text || '')
+    .replace(/\[\d{1,2}:\d{2}(?::\d{2})?\]/g, ' ')
+    .replace(/\b\d{1,2}:\d{2}(?::\d{2})?(?:\.\d+)?\b/g, ' ')
+    .replace(/[“”]/g, '"')
+    .split(/\s+/)
+    .map((word) => word.replace(/^[^A-Za-z0-9$%]+|[^A-Za-z0-9%]+$/g, ''))
+    .filter(Boolean);
+}
+
+function extractTeachNumbers(text) {
+  // Keep a number only with its unit or a nearby claim. Bare 20/60 are crumbs.
+  const words = teachCaptionWords(text);
+  const found = [];
+  const seen = new Set();
+  const numberRe = /^(?:\$)?(\d[\d,]*(?:\.\d+)?)(%?)$/;
+  const unitRe = new RegExp(`^(?:${NUMBER_UNITS})$`, 'i');
+  const verbRe = new RegExp(`\\b(?:${NUMBER_CLAIM_VERBS})\\b`, 'i');
+
+  for (let i = 0; i < words.length; i += 1) {
+    const match = words[i].match(numberRe);
+    if (!match) continue;
+    const nearby = words.slice(i + 1, i + 3);
+    const unit = nearby.find((word) => unitRe.test(word));
+    const hasPercent = match[2] === '%' || /%/.test(words[i]);
+    if (!unit && !hasPercent) continue;
+
+    const windowText = words.slice(Math.max(0, i - 6), Math.min(words.length, i + 7)).join(' ');
+    const verbMatch = windowText.match(verbRe);
+    const number = match[1];
+    let claim = hasPercent ? `${number}%` : `${number} ${String(unit).toLowerCase()}`;
+    if (verbMatch) claim += ` to ${verbMatch[0].toLowerCase()}`;
+    const key = claim.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    found.push(claim);
+  }
+  return found.slice(0, 8);
+}
+
+function extractTeachMechanisms(text) {
+  // Named only: "Overton window", "omakase model". Drop quotes, swears, crumbs.
+  const found = [];
+  const seen = new Set();
+  const add = (value) => {
+    const token = String(value || '').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!token || TEACH_SWEAR_RE.test(token)) return;
+    if (seen.has(token) || MECHANISM_STOP.has(token) || GENERIC_MECHANISM_LEFT.has(token)) return;
+    if (token.length < 4 && !/\d/.test(token)) return;
+    seen.add(token);
+    found.push(token);
+  };
+
+  const raw = String(text || '');
+  const namedRe = new RegExp(`\\b([A-Za-z][A-Za-z0-9+-]{2,})\\s+(${MECHANISM_HEADS})\\b`, 'gi');
+  for (const match of raw.matchAll(namedRe)) {
+    const left = String(match[1] || '').toLowerCase();
+    if (GENERIC_MECHANISM_LEFT.has(left) || MECHANISM_STOP.has(left)) continue;
+    add(`${match[1]} ${match[2]}`);
+  }
+  for (const match of raw.matchAll(/\b(\d+[A-Za-z][A-Za-z0-9]+)\b/g)) add(match[1]);
+  return found.slice(0, 8);
+}
+
+function oneTeachCheck(mechanisms, numbers, title) {
+  if (mechanisms[0]) {
+    const name = mechanisms[0];
+    const named = new RegExp(`\\b(?:${MECHANISM_HEADS})\\b`, 'i').test(name);
+    if (named && !/^(the|a|an)\s/i.test(name)) return `what is the ${name}?`;
+    return `what is ${name}?`;
+  }
+  if (numbers[0]) return `what does ${numbers[0]} measure in this chapter?`;
+  return `what is the point of ${title || 'this chapter'}?`;
+}
+
+function quoteYoutubeUrl(url) {
+  return `"${String(url || '').replace(/"/g, '')}"`;
+}
+
+function formatTeachLesson({ url, section, chapters, chapter, cues, title } = {}) {
+  const total = Array.isArray(chapters) && chapters.length ? chapters.length : 1;
+  const heading = String(chapter?.title || 'full video').trim().toLowerCase();
+  const videoTitle = String(title || '').trim().toLowerCase();
+  const body = (cues || []).map((cue) => cue.text).join(' ');
+  const numbers = extractTeachNumbers(body);
+  const mechanisms = extractTeachMechanisms(body);
+  const lines = [
+    `section ${section}/${total}  ${heading}`,
+  ];
+  if (videoTitle) lines.push(videoTitle);
+  lines.push('');
+  lines.push('numbers');
+  if (numbers.length) lines.push(...numbers);
+  else lines.push('none');
+  lines.push('');
+  lines.push('mechanisms');
+  if (mechanisms.length) lines.push(...mechanisms);
+  else lines.push('none');
+  lines.push('');
+  lines.push('check');
+  lines.push(oneTeachCheck(mechanisms, numbers, heading));
+  if (section < total) {
+    lines.push('');
+    lines.push(`next: atris youtube teach ${quoteYoutubeUrl(url)} --section ${section + 1}`);
+  } else {
+    lines.push('');
+    lines.push('next: last section');
+  }
+  return lines.join('\n');
+}
+
+function teachBriefRel(id, section) {
+  return `atris/wiki/briefs/youtube-${id}-s${section}.md`;
+}
+
+function fileTeachBrief({ cwd, url, section, lesson, now } = {}) {
+  try {
+    const id = videoIdFromUrl(url);
+    if (!id || !cwd) return null;
+    const wikiDir = path.join(cwd, 'atris', 'wiki');
+    if (!fs.existsSync(wikiDir)) return null;
+    const rel = teachBriefRel(id, section);
+    const briefsDir = path.join(cwd, 'atris', 'wiki', 'briefs');
+    fs.mkdirSync(briefsDir, { recursive: true });
+    const date = dateStamp(now);
+    const header = [
+      String(lesson || '').split('\n')[0] || `teach section ${section}`,
+      '',
+      `date: ${date}`,
+      `source: ${url}`,
+      `section: ${section}`,
+      'rail: atris youtube teach, one chapter from local captions',
+    ].join('\n');
+    fs.writeFileSync(path.join(cwd, rel), `${header}\n\n${lesson}\n`);
+
+    const journalPath = path.join(cwd, 'atris', 'logs', date.slice(0, 4), `${date}.md`);
+    fs.mkdirSync(path.dirname(journalPath), { recursive: true });
+    let existing = '';
+    if (fs.existsSync(journalPath)) existing = fs.readFileSync(journalPath, 'utf8');
+    const line = `- [claimable] taught: section ${section} -> ${rel}`;
+    if (!existing.includes(line)) {
+      const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+      fs.writeFileSync(journalPath, `${existing}${prefix}${line}\n`);
+    }
+    return rel;
+  } catch {
+    return null;
+  }
+}
+
+function ensureTeachApply({ cwd, url, section, now, output } = {}) {
+  const id = videoIdFromUrl(url);
+  return applyGate.ensureApply({
+    cwd,
+    source: url,
+    rel: id ? applySidecarRel(`${id}-s${section}`) : null,
+    now,
+    output,
+    incompleteMessage: TEACH_APPLY_NEXT_MESSAGE,
+    required: false,
+  });
+}
+
+async function extractTeachSource(youtubeUrl, deps = {}) {
+  if (typeof deps.extractTeachSource === 'function') {
+    return deps.extractTeachSource(youtubeUrl, deps);
+  }
+  const runner = deps.spawnSync || spawnSync;
+  const result = runner('yt-dlp', ['-J', '--skip-download', '--no-warnings', youtubeUrl], {
+    encoding: 'utf8',
+    timeout: 20000,
+    maxBuffer: 10 * 1024 * 1024,
+  });
+  if (result.error || result.status !== 0 || !result.stdout) return null;
+
+  let info;
+  try {
+    info = JSON.parse(result.stdout);
+  } catch {
+    return null;
+  }
+
+  const selected = chooseCaptionTrack(info);
+  if (!selected?.track?.url) return null;
+  const rawCaption = await (deps.fetchCaptionText || fetchCaptionText)(selected.track.url);
+  const cues = parseCaptionCues(rawCaption);
+  if (!cues.length) return null;
+
+  return {
+    id: info.id || videoIdFromUrl(youtubeUrl),
+    title: info.title || '',
+    url: youtubeUrl,
+    durationSeconds: Number(info.duration || 0) || undefined,
+    language: selected.language || 'unknown',
+    chapters: normalizeChapters(info.chapters, info.duration),
+    cues,
+  };
+}
+
+async function runYoutubeTeach(args = [], deps = {}) {
+  const output = deps.output || ((line = '') => console.log(line));
+  let parsed;
+  try {
+    parsed = parseTeachArgs(args);
+  } catch (err) {
+    output(err.message || YTTEACH_USAGE);
+    return 2;
+  }
+  if (parsed.help) {
+    showYoutubeHelp(output, deps.commandName || 'atris youtube');
+    return 0;
+  }
+
+  const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, deps);
+  if (!source || !Array.isArray(source.cues) || !source.cues.length) {
+    output('no english captions for this url. teach stays local and will not call process.');
+    return 2;
+  }
+
+  const chapters = normalizeChapters(source.chapters, source.durationSeconds);
+  if (parsed.section > chapters.length) {
+    output(`section ${parsed.section} is past ${chapters.length} chapters. try --section ${chapters.length}`);
+    return 2;
+  }
+
+  const chapter = chapters[parsed.section - 1];
+  const cues = sliceCuesForChapter(source.cues, chapter);
+  const lesson = formatTeachLesson({
+    url: parsed.url,
+    section: parsed.section,
+    chapters,
+    chapter,
+    cues,
+    title: source.title,
+  });
+  output(lesson);
+
+  if (!parsed.save) return 0;
+
+  fileTeachBrief({
+    cwd: deps.cwd || process.cwd(),
+    url: parsed.url,
+    section: parsed.section,
+    lesson,
+    now: deps.now,
+  });
+  const ensureApply = deps.ensureApply || ensureTeachApply;
+  return ensureApply({
+    cwd: deps.cwd || process.cwd(),
+    url: parsed.url,
+    section: parsed.section,
+    now: deps.now,
+    output,
+  });
+}
+
 async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   if (argv[0] === 'search') {
@@ -1742,11 +2323,21 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
     }
     return code;
   }
+  if (argv[0] === 'unsave') {
+    const code = runYoutubeUnsave(argv.slice(1), deps);
+    if (!deps.output && !deps.spawnSync && !deps.runner && !deps.expander) process.exit(code);
+    return code;
+  }
   if (argv[0] === 'notes') {
     const code = runYoutubeNotes(argv.slice(1), deps);
     if (!deps.output && !deps.spawnSync && !deps.runner && !deps.expander) process.exit(code);
     return code;
   }
+  if (argv[0] === 'teach') {
+    const code = await runYoutubeTeach(argv.slice(1), { ...deps, output });
+    if (!deps.output && !deps.extractTeachSource && !deps.spawnSync && !deps.runner) process.exit(code);
+    return code;
+  }
   if (argv[0] === 'digest') {
     const code = runYoutubeDigest(argv.slice(1), { ...deps, output });
     if (!deps.output && !deps.runner) process.exit(code);
@@ -1767,8 +2358,8 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
     const data = await processYoutube(options, deps);
     output(options.json ? JSON.stringify(data, null, 2) : formatYoutubeResult(data));
   } catch (err) {
-    output(err.message);
-    status = 1;
+    if (!err.applyRequired) output(err.message);
+    status = Number.isInteger(err.exitCode) ? err.exitCode : 1;
   }
   if (!deps.output && !deps.apiRequestJson && !deps.ensureValidCredentials && !deps.ensureBilledCommandAuth && !deps.extractLocalTranscript) {
     process.exit(status);
@@ -1786,6 +2377,10 @@ module.exports = {
   shouldRetryWithLocalTranscript,
   formatYoutubeResult,
   fileBriefFromNotes,
+  ensureNotesApply,
+  unsaveYoutubeNotes,
+  APPLY_NEXT_MESSAGE,
+  PROCESS_APPLY_MESSAGE,
   isPlaylistUrl,
   parseNotesArgs,
   expandNotesTargets,
@@ -1801,5 +2396,13 @@ module.exports = {
   parseSearchArgs,
   parseSearchStdout,
   formatSearchResults,
+  parseTeachArgs,
+  parseCaptionCues,
+  normalizeChapters,
+  sliceCuesForChapter,
+  formatTeachLesson,
+  extractTeachNumbers,
+  extractTeachMechanisms,
+  extractTeachSource,
   youtubeCommand,
 };