atris 3.57.4 → 3.58.6

package/commands/youtube.js

@@ -31,6 +31,8 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`       ${commandName} search --paid "<query>" [--limit N] [--json]`);
   output(`       ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine] [--save]`);
   output(`       ${commandName} teach <youtube-url> [--section N] [--save] [--recap TEXT] [--skip]`);
+  output(`       ${commandName} teach owed [--json]`);
+  output(`       ${commandName} teach next [--json]`);
   output(`       ${commandName} unsave <url-or-id>`);
   output(`       ${commandName} process <youtube-url> [options]`);
   output(`       ${commandName} digest [--days N]`);
@@ -40,14 +42,14 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`       ${commandName} watch tick`);
   output(`       ${commandName} <youtube-url> [options]`);
   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 to stdout; ephemeral unless --save');
-  output('teach = one chapter from local captions; ephemeral unless --save');
-  output('rich ephemeral notes/teach print one apply next-step (no files)');
-  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('search = free local discovery (ytsearch / yt-dlp), returns youtu.be links; rich free search writes one apply and a failing keep/revert pack; thin hands off to teach');
+  output('search --paid = 5 credits, watch permalinks + titles from Atris; rich paid search writes one apply and a failing keep/revert pack; thin hands off to teach');
+  output('notes = free local notes to stdout; ephemeral unless --save; hands off to teach');
+  output('teach = one chapter from local captions; bare teach resumes unpaid checks, then the next chapter after recap or skip');
+  output('rich ephemeral notes/teach print one apply next-step and one failing check (no files)');
+  output('process = 5 credits cloud knowledge (needs a filled Apply); rich process writes one apply and a failing keep/revert pack');
+  output('digest = one decision page from this week\'s video briefs; rich digest writes one apply and a failing keep/revert pack');
+  output('watch = subscribed channels turn into briefs without a human; add hands off to tick; tick hands off to teach when it briefed');
   output('Process a YouTube video through Atris using timestamped transcript-first analysis.');
   output('Falls back to cloud video processing when local captions are unavailable.');
   output('');
@@ -58,6 +60,8 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output('  --section <n>       Chapter to teach, 1-based (teach only, default: 1)');
   output('  --recap <text>      Unlock the next teach section with the unpaid check');
   output('  --skip              Unlock the next teach section without answering');
+  output('  owed                Print the unpaid teach check (no network)');
+  output('  next                Next unlocked chapter (no url, no billing)');
   output('  --unsave            Delete filed brief, apply stub, and matching notes/teach experiment packs (no paid calls)');
   output('  --query, -q <text>  Focus question for the analysis');
   output('  --agent <id>        Agent id to store knowledge against');
@@ -77,6 +81,7 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   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} teach next`);
   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`);
@@ -206,8 +211,16 @@ function youtubeFailureError(result) {
     ? ' Run "atris login --force".'
     : result.status === 402
       ? ' Check Atris credits.'
-      : '';
-  return new Error(`YouTube processing failed (${result.status}): ${resultErrorText(result)}.${hint}`);
+      : result.status === 502
+        ? ' YouTube processing is unavailable; retry in a few seconds.'
+        : '';
+  const credits = paidSearchCredits(result.data);
+  const refundHint = result.status === 502 && creditsRefundedExplicitly(credits)
+    ? ' credits refunded.'
+    : '';
+  const lines = [`YouTube processing failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
+  lines.push(...formatCreditsLines(credits));
+  return new Error(lines.join('\n'));
 }
 
 function captionHostAllowed(urlString) {
@@ -401,33 +414,110 @@ function parseCaptionText(raw) {
   return segments.join(' ');
 }
 
+function parseYtDlpInfoJson(result) {
+  const raw = String((result && result.stdout) || '').trim();
+  if (!raw) return null;
+  try {
+    const info = JSON.parse(raw);
+    return info && typeof info === 'object' && !Array.isArray(info) ? info : null;
+  } catch {
+    return null;
+  }
+}
+
+function localCaptionNames(id) {
+  // scripts/det/ytnotes keeps the same VTT names (not clean.txt).
+  return [
+    `yt_${id}.en.vtt`,
+    `yt_${id}.en-orig.vtt`,
+    `yt_${id}.en-US.vtt`,
+    `yt_${id}.en-GB.vtt`,
+    `yt_${id}.clean.txt`,
+  ];
+}
+
+function captionLookupIds({ url, id } = {}) {
+  const ids = [];
+  const seen = new Set();
+  const add = (value) => {
+    const text = String(value || '').trim();
+    if (!text || seen.has(text)) return;
+    seen.add(text);
+    ids.push(text);
+  };
+  add(id);
+  add(videoIdFromUrl(url));
+  return ids;
+}
+
+function readLocalCaptionText({ url, id, workDir } = {}) {
+  if (!workDir) return '';
+  for (const videoId of captionLookupIds({ url, id })) {
+    for (const name of localCaptionNames(videoId)) {
+      const abs = path.join(workDir, name);
+      try {
+        if (!fs.existsSync(abs)) continue;
+        const text = fs.readFileSync(abs, 'utf8');
+        if (String(text).trim()) return text;
+      } catch {
+        // try the next written caption file
+      }
+    }
+  }
+  return '';
+}
+
+async function loadCaptionRaw(info, youtubeUrl, deps = {}) {
+  const payload = info && typeof info === 'object' ? info : {};
+  const selected = chooseCaptionTrack(payload);
+  let raw = '';
+  if (selected?.track?.url) {
+    raw = await (deps.fetchCaptionText || fetchCaptionText)(selected.track.url);
+  }
+  if (String(raw || '').trim()) {
+    return { raw, language: selected?.language || 'unknown' };
+  }
+  const local = readLocalCaptionText({
+    url: youtubeUrl,
+    id: payload.id,
+    workDir: deps.workDir,
+  });
+  if (!String(local || '').trim()) return null;
+  return { raw: local, language: selected?.language || 'en' };
+}
+
+function ytDlpInfoArgs(youtubeUrl) {
+  return ['-J', '--skip-download', '--no-warnings', '--no-playlist', youtubeUrl];
+}
+
+function teachSourceVideoId(info, youtubeUrl) {
+  const fromUrl = videoIdFromUrl(youtubeUrl);
+  const fromInfo = info && info.id;
+  const entries = info && Array.isArray(info.entries) ? info.entries : [];
+  const fromEntry = entries[0] && entries[0].id;
+  if (info && (info._type === 'playlist' || entries.length)) {
+    return fromUrl || fromEntry || fromInfo;
+  }
+  return fromInfo || fromUrl;
+}
+
 async function extractLocalTranscript(youtubeUrl, deps = {}) {
   if (process.env.ATRIS_YOUTUBE_LOCAL_TRANSCRIPT === '0') return null;
   const runner = deps.spawnSync || spawnSync;
-  const result = runner('yt-dlp', ['-J', '--skip-download', '--no-warnings', youtubeUrl], {
+  const result = runner('yt-dlp', ytDlpInfoArgs(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 transcript = parseCaptionText(rawCaption);
+  const info = parseYtDlpInfoJson(result);
+  const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
+  const transcript = parseCaptionText(loaded && loaded.raw);
   if (!transcript) return null;
 
   return {
     transcriptText: transcript.slice(0, LOCAL_TRANSCRIPT_MAX_CHARS),
-    language: selected.language || 'unknown',
-    durationSeconds: Number(info.duration || 0) || undefined,
+    language: loaded.language || 'unknown',
+    durationSeconds: Number((info && info.duration) || 0) || undefined,
   };
 }
 
@@ -463,6 +553,12 @@ async function processYoutube(options, deps = {}) {
     if (!result.ok && result.status === 401 && !auth.minted) {
       const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
       if (remint?.ok && remint.token) {
+        if (!options.json) {
+          const print = typeof deps.output === 'function' ? deps.output : () => {};
+          for (const line of formatCreditsLines(paidSearchCredits(result.data))) {
+            print(line);
+          }
+        }
         auth = remint;
         result = await apiFn('/agent/process_youtube', {
           method: 'POST',
@@ -479,7 +575,10 @@ async function processYoutube(options, deps = {}) {
   const localExtractor = deps.extractLocalTranscript || extractLocalTranscript;
   let localTranscript = null;
   try {
-    localTranscript = await localExtractor(options.youtubeUrl, deps);
+    localTranscript = await localExtractor(options.youtubeUrl, {
+      ...deps,
+      workDir: deps.workDir || notesWorkDir(deps),
+    });
   } catch {
     localTranscript = null;
   }
@@ -496,6 +595,12 @@ async function processYoutube(options, deps = {}) {
     if (transcriptResult.status === 401 || transcriptResult.status === 402 || transcriptResult.status === 400) {
       throw youtubeFailureError(transcriptResult);
     }
+    if (!options.json) {
+      const print = typeof deps.output === 'function' ? deps.output : () => {};
+      for (const line of formatCreditsLines(paidSearchCredits(transcriptResult.data))) {
+        print(line);
+      }
+    }
   }
 
   const result = await requestYoutube(buildYoutubePayload(options));
@@ -507,6 +612,17 @@ async function processYoutube(options, deps = {}) {
   return result.data;
 }
 
+function processAnalysisText(data) {
+  return data?.video_analysis || data?.analysis || data?.result || '';
+}
+
+function printProcessLearnerGate(data, { json = false } = {}, output) {
+  printLearnerCheckGate(output, notesLessonFromText(processAnalysisText(data)), {
+    includeCheck: true,
+    json,
+  });
+}
+
 function formatYoutubeResult(data) {
   const lines = [];
   const metadata = data?.metadata || {};
@@ -521,12 +637,9 @@ function formatYoutubeResult(data) {
       : '';
     lines.push(`Processing: ${method}${source}`);
   }
-  if (data?.credits_used !== undefined || data?.credits_remaining !== undefined) {
-    const used = data.credits_used !== undefined ? data.credits_used : '?';
-    const remaining = data.credits_remaining !== undefined ? data.credits_remaining : '?';
-    lines.push(`Credits: ${used} used, ${remaining} remaining`);
-  }
-  const analysis = data?.video_analysis || data?.analysis || data?.result;
+  const creditLines = formatCreditsLines(paidSearchCredits(data));
+  if (creditLines.length) lines.push(...creditLines);
+  const analysis = processAnalysisText(data);
   if (analysis) {
     lines.push('');
     lines.push(String(analysis).trim());
@@ -535,11 +648,13 @@ function formatYoutubeResult(data) {
 }
 
 function videoIdFromUrl(url) {
-  const text = String(url || '');
+  const text = String(url || '').split('#')[0];
   const watch = text.match(/[?&]v=([^&]+)/);
   if (watch) return watch[1];
   const short = text.match(/youtu\.be\/([^?&/]+)/);
-  return short ? short[1] : null;
+  if (short) return short[1];
+  const pathId = text.match(/\/(?:shorts|embed|live|v|e)\/([^?&/]+)/i);
+  return pathId ? pathId[1] : null;
 }
 
 function videoIdFromArg(arg) {
@@ -553,7 +668,7 @@ function videoIdFromArg(arg) {
 function looksLikeYoutubeUrl(arg) {
   const text = String(arg || '').trim();
   if (!text || text.startsWith('-')) return false;
-  return /youtube\.com|youtu\.be/i.test(text);
+  return /youtube\.com|youtu\.be|youtube-nocookie\.com/i.test(text);
 }
 
 function isPlaylistUrl(url) {
@@ -567,22 +682,24 @@ function parseNotesArgs(argv = []) {
   let help = false;
   let save = false;
   let unsave = false;
+  let json = false;
   for (const raw of argv) {
     const arg = String(raw);
     if (arg === '--help' || arg === '-h' || arg === 'help') help = true;
     else if (arg === '--save') save = true;
     else if (arg === '--unsave') unsave = true;
+    else if (arg === '--json') json = 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 === '--save' || arg === '--unsave' || arg === '--json') 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, save, unsave };
+  return { urls, engine, help, save, unsave, json };
 }
 
 function dateStamp(now) {
@@ -676,11 +793,19 @@ function readNotesText({ url, workDir } = {}) {
   }
 }
 
+function notesWorkDir(deps = {}) {
+  return deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
+}
+
+function keptPrintedNotes({ url, workDir } = {}) {
+  return Boolean(String(readNotesText({ url, workDir }) || '').trim());
+}
+
 function saveRichNotes(url, deps = {}) {
   const workDir = deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
   const lesson = notesLessonFromText(readNotesText({ url, workDir }));
   if (isThinTeachLesson(lesson)) {
-    return { thin: true, brief: null, packRel: null };
+    return { thin: true, brief: null, packRel: null, lesson };
   }
   const brief = fileNotesBrief(url, deps);
   const id = videoIdFromUrl(url);
@@ -691,20 +816,21 @@ function saveRichNotes(url, deps = {}) {
     slug: id ? notesExperimentSlug(id) : null,
     applyRel: id ? applySidecarRel(id) : null,
   });
-  return { thin: false, brief, packRel };
+  return { thin: false, brief, packRel, lesson };
 }
 
 function ensureNotesApply({ cwd, url, packRel, now, output } = {}) {
   const id = videoIdFromUrl(url);
   const pack = packRel || (id ? notesExperimentRel(id) : null);
+  const slug = pack ? path.basename(pack) : null;
   return applyGate.ensureApply({
     cwd,
     source: url,
     rel: id ? applySidecarRel(id) : null,
     now,
     output,
-    incompleteMessage: pack
-      ? `next: apply ${pack}. keep only if measure.py moves 0→1`
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
       : APPLY_NEXT_MESSAGE,
     required: false,
     change: pack ? `apply ${pack}` : undefined,
@@ -787,6 +913,8 @@ function unsaveYoutubeNotes(target, deps = {}) {
   }
   for (const rel of listTeachSidecarRels(cwd, id)) add(rel);
   add(notesExperimentRel(id));
+  add(processApplyRel(id));
+  add(processExperimentRel(id));
   for (const section of sections) add(teachExperimentRel(id, section));
 
   const removed = [];
@@ -815,6 +943,9 @@ function runYoutubeUnsave(args = [], deps = {}) {
     const status = unsaveYoutubeNotes(target, deps);
     if (status !== 0) code = status;
   }
+  if (code === 0 && parsed.json !== true && deps.json !== true) {
+    printWatchSearchNext(output);
+  }
   return code;
 }
 
@@ -831,6 +962,85 @@ function ensureProcessApply({ cwd, url, now, output } = {}) {
   });
 }
 
+function processExperimentSlug(id) {
+  return `process-${experimentIdToken(id)}`;
+}
+
+function processExperimentRel(id) {
+  return `atris/experiments/${processExperimentSlug(id)}`;
+}
+
+function processApplyRel(id) {
+  return applyGate.applySidecarRel('process', experimentIdToken(id));
+}
+
+function saveRichProcess({ cwd, url, lesson } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  const id = videoIdFromUrl(url);
+  const packRel = fileTeachExperiment({
+    cwd,
+    url,
+    lesson,
+    slug: id ? processExperimentSlug(id) : null,
+    applyRel: id ? processApplyRel(id) : null,
+  });
+  return { thin: false, packRel, lesson, source: url };
+}
+
+function ensureProcessLearnerApply({ cwd, url, packRel, now, output, source } = {}) {
+  const id = videoIdFromUrl(url);
+  const pack = packRel || (id ? processExperimentRel(id) : null);
+  const slug = pack ? path.basename(pack) : null;
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  return applyGate.ensureApply({
+    cwd,
+    source: source || url || (id ? `process:${id}` : 'process'),
+    rel: id ? processApplyRel(id) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('process'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
+  });
+}
+
+function mintRichProcess({ cwd, url, data, now, output, ensureApply, json } = {}) {
+  const print = typeof output === 'function' ? output : (line = '') => console.log(line);
+  const lesson = notesLessonFromText(processAnalysisText(data));
+  if (isThinTeachLesson(lesson)) {
+    printProcessLearnerGate(data, { json }, print);
+    return 0;
+  }
+  const saved = saveRichProcess({ cwd, url, lesson });
+  const applyFn = ensureApply || ensureProcessLearnerApply;
+  const applyCode = applyFn({
+    cwd,
+    url,
+    packRel: saved.packRel,
+    now,
+    output: print,
+    source: url,
+  });
+  if (ensureApply) return applyCode;
+  const id = videoIdFromUrl(url);
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: id ? processApplyRel(id) : null,
+    lesson: saved.lesson,
+    output: print,
+    json,
+  });
+  if (baseline !== 0) return baseline;
+  return applyCode;
+}
+
 const DIGEST_ENGINE_TIMEOUT_MS = 240000;
 const DEFAULT_DIGEST_DAYS = 7;
 
@@ -977,6 +1187,113 @@ function appendDigestJournal({ cwd, date, relDigest }) {
   fs.writeFileSync(journalPath, `${existing}${prefix}${line}\n`);
 }
 
+function digestExperimentSlug(date) {
+  return `digest-${String(date || '').slice(0, 10)}`;
+}
+
+function digestExperimentRel(date) {
+  return `atris/experiments/${digestExperimentSlug(date)}`;
+}
+
+function digestApplyRel(date) {
+  return applyGate.applySidecarRel('digest', String(date || '').slice(0, 10));
+}
+
+function ensureDigestApply({ cwd, date, packRel, now, output, source } = {}) {
+  const stamp = String(date || '').slice(0, 10);
+  const pack = packRel || (stamp ? digestExperimentRel(stamp) : null);
+  const slug = pack ? path.basename(pack) : null;
+  return applyGate.ensureApply({
+    cwd,
+    source: source || (stamp ? `digest:${stamp}` : 'digest'),
+    rel: stamp ? digestApplyRel(stamp) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('digest'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
+  });
+}
+
+function saveRichDigest({ cwd, date, lesson, source } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  const packRel = fileTeachExperiment({
+    cwd,
+    lesson,
+    slug: date ? digestExperimentSlug(date) : null,
+    applyRel: date ? digestApplyRel(date) : null,
+  });
+  return { thin: false, packRel, lesson, source };
+}
+
+function watchExperimentSlug(id) {
+  return `watch-${experimentIdToken(id)}`;
+}
+
+function watchExperimentRel(id) {
+  return `atris/experiments/${watchExperimentSlug(id)}`;
+}
+
+function watchApplyRel(id) {
+  return applyGate.applySidecarRel('watch', experimentIdToken(id));
+}
+
+function ensureWatchWiki(cwd) {
+  if (!cwd) return;
+  fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+}
+
+function ensureWatchApply({ cwd, url, packRel, now, output, source } = {}) {
+  const id = videoIdFromUrl(url);
+  const pack = packRel || (id ? watchExperimentRel(id) : null);
+  const slug = pack ? path.basename(pack) : null;
+  ensureWatchWiki(cwd);
+  return applyGate.ensureApply({
+    cwd,
+    source: source || url || (id ? `watch:${id}` : 'watch'),
+    rel: id ? watchApplyRel(id) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('watch'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
+  });
+}
+
+function firstRichWatchLesson(urls, workDir) {
+  for (const url of Array.isArray(urls) ? urls : []) {
+    if (!url) continue;
+    const lesson = notesLessonFromText(readNotesText({ url, workDir }));
+    if (!isThinTeachLesson(lesson)) return { url, lesson };
+  }
+  return null;
+}
+
+function saveRichWatch({ cwd, url, lesson } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  const id = videoIdFromUrl(url);
+  const packRel = fileTeachExperiment({
+    cwd,
+    url,
+    lesson,
+    slug: id ? watchExperimentSlug(id) : null,
+    applyRel: id ? watchApplyRel(id) : null,
+  });
+  return { thin: false, packRel, lesson, source: url };
+}
+
 function runYoutubeDigest(args = [], deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   let options;
@@ -996,6 +1313,7 @@ function runYoutubeDigest(args = [], deps = {}) {
   const briefs = collectVideoBriefs({ cwd, now, days: options.days });
   if (!briefs.length) {
     output(`no video briefs in the last ${options.days} days`);
+    printWatchSearchNext(output);
     return 0;
   }
 
@@ -1023,7 +1341,32 @@ function runYoutubeDigest(args = [], deps = {}) {
   fs.writeFileSync(path.join(cwd, relDigest), `${header}\n\n${text}\n`);
   appendDigestJournal({ cwd, date, relDigest });
   output(`digest filed: ${relDigest} (${briefs.length} briefs)`);
-  return 0;
+  const lesson = notesLessonFromText(text);
+  if (isThinTeachLesson(lesson)) {
+    printLearnerCheckGate(output, lesson, { includeCheck: true });
+    printWatchTickNext(output);
+    return 0;
+  }
+
+  const saved = saveRichDigest({ cwd, date, lesson, source: relDigest });
+  const ensureApply = deps.ensureApply || ensureDigestApply;
+  const applyCode = ensureApply({
+    cwd,
+    date,
+    packRel: saved.packRel,
+    now,
+    output,
+    source: relDigest,
+  });
+  if (deps.ensureApply) return applyCode;
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: digestApplyRel(date),
+    lesson,
+    output,
+  });
+  if (baseline !== 0) return baseline;
+  return applyCode;
 }
 
 function watchStatePath(cwd = process.cwd()) {
@@ -1130,6 +1473,7 @@ function defaultChannelFetcher(videosUrl, deps = {}) {
   const result = spawn('yt-dlp', [
     '--no-update',
     '--flat-playlist',
+    '--no-warnings',
     '--playlist-end',
     '3',
     '--print',
@@ -1140,11 +1484,13 @@ function defaultChannelFetcher(videosUrl, deps = {}) {
     timeout: 60000,
     maxBuffer: 2 * 1024 * 1024,
   });
+  const videos = parseFlatPlaylist(result && result.stdout);
+  if (videos.length) return videos;
   if (result.error || result.status !== 0) {
     const detail = String(result.stderr || result.error?.message || 'fetch failed').trim();
     throw new Error(detail || 'fetch failed');
   }
-  return parseFlatPlaylist(result.stdout);
+  return videos;
 }
 
 function defaultNotesRunner(url, deps = {}) {
@@ -1172,6 +1518,22 @@ function markSeen(state, channel, id, timestamp) {
   state.seenByChannel[channel][id] = timestamp;
 }
 
+const WATCH_TICK_NEXT = 'next: atris youtube watch tick';
+const WATCH_ADD_NEXT = 'next: atris youtube watch add <channel-url-or-@handle>';
+const WATCH_SEARCH_NEXT = 'next: atris youtube search " "';
+
+function printWatchTickNext(output) {
+  output(WATCH_TICK_NEXT);
+}
+
+function printWatchAddNext(output) {
+  output(WATCH_ADD_NEXT);
+}
+
+function printWatchSearchNext(output) {
+  output(WATCH_SEARCH_NEXT);
+}
+
 function addWatchChannel(channelInput, deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   if (!channelInput) {
@@ -1191,6 +1553,7 @@ function addWatchChannel(channelInput, deps = {}) {
   const state = loadWatchState(statePath);
   if (state.channels.some((row) => row.channel === channel)) {
     output(`already watching ${channel}`);
+    printWatchTickNext(output);
     return 0;
   }
 
@@ -1200,6 +1563,7 @@ function addWatchChannel(channelInput, deps = {}) {
   });
   saveWatchState(statePath, state);
   output(`watching ${channel}`);
+  printWatchTickNext(output);
   return 0;
 }
 
@@ -1208,6 +1572,7 @@ function listWatchChannels(deps = {}) {
   const state = loadWatchState(resolveWatchStatePath(deps));
   if (!state.channels.length) {
     output('no channels watched');
+    printWatchAddNext(output);
     return 0;
   }
 
@@ -1215,6 +1580,7 @@ function listWatchChannels(deps = {}) {
     const count = Object.keys(channelSeenMap(state, row.channel)).length;
     output(`${index + 1}. ${row.channel} (${count} seen)`);
   });
+  printWatchTickNext(output);
   return 0;
 }
 
@@ -1231,6 +1597,11 @@ function removeWatchChannel(rawNumber, deps = {}) {
   const [removed] = state.channels.splice(index - 1, 1);
   saveWatchState(statePath, state);
   output(`removed ${removed.channel}`);
+  if (!state.channels.length) {
+    printWatchAddNext(output);
+  } else {
+    printWatchTickNext(output);
+  }
   return 0;
 }
 
@@ -1248,6 +1619,8 @@ async function tickWatch(deps = {}) {
   const state = loadWatchState(statePath);
   let totalNew = 0;
   let totalBriefed = 0;
+  let firstBriefedUrl = null;
+  const briefedUrls = [];
 
   for (const row of state.channels) {
     const videosUrl = channelVideosUrl(row.channel);
@@ -1294,6 +1667,8 @@ async function tickWatch(deps = {}) {
       }
       markSeen(state, row.channel, video.id, timestamp);
       briefed += 1;
+      briefedUrls.push(url);
+      if (!firstBriefedUrl) firstBriefedUrl = url;
     }
 
     if (!isFresh) {
@@ -1311,6 +1686,41 @@ async function tickWatch(deps = {}) {
 
   output(`total: ${totalNew} new, ${totalBriefed} briefed`);
   saveWatchState(statePath, state);
+  if (totalBriefed > 0) {
+    const rich = firstRichWatchLesson(briefedUrls, workDir);
+    if (rich) {
+      const saved = saveRichWatch({ cwd, url: rich.url, lesson: rich.lesson });
+      const ensureApply = deps.ensureApply || ensureWatchApply;
+      const applyCode = ensureApply({
+        cwd,
+        url: rich.url,
+        packRel: saved.packRel,
+        now,
+        output,
+        source: rich.url,
+      });
+      if (deps.ensureApply) return applyCode;
+      const id = videoIdFromUrl(rich.url);
+      const baseline = proveSavedLearnerBaseline({
+        cwd,
+        applyRel: id ? watchApplyRel(id) : null,
+        lesson: rich.lesson,
+        output,
+      });
+      if (baseline !== 0) return baseline;
+      return applyCode;
+    }
+    if (firstBriefedUrl) {
+      const lesson = notesLessonFromText(readNotesText({ url: firstBriefedUrl, workDir }));
+      printLearnerCheckGate(output, lesson, { includeCheck: true });
+      printYoutubeTeachNext(firstBriefedUrl, {}, output);
+      return 0;
+    }
+    printYoutubeTeachNext(firstBriefedUrl, {}, output);
+    return 0;
+  }
+  if (!state.channels.length) printWatchAddNext(output);
+  else printWatchSearchNext(output);
   return 0;
 }
 
@@ -1342,11 +1752,13 @@ function defaultPlaylistExpander(playlistUrl, deps = {}) {
     timeout: 60000,
     maxBuffer: 2 * 1024 * 1024,
   });
+  const videos = parseFlatPlaylist(result && result.stdout);
+  if (videos.length) return videos;
   if (result.error || (result.status != null && result.status !== 0)) {
     const detail = String(result.stderr || result.error?.message || 'playlist expand failed').trim();
     throw new Error(detail || 'playlist expand failed');
   }
-  return parseFlatPlaylist(result.stdout);
+  return videos;
 }
 
 function defaultNotesItemRunner(url, engine, deps = {}) {
@@ -1440,14 +1852,20 @@ function runOneNotesItem(item, engine, deps = {}) {
   }
 
   const started = readNowMs(deps);
-  let status = 1;
+  let result = { status: 1 };
   try {
-    status = readRunnerStatus(invokeNotesRunner(item.url, engine, deps));
-  } catch {
-    status = 1;
+    result = invokeNotesRunner(item.url, engine, deps);
+  } catch (err) {
+    result = { status: 1, stderr: String((err && err.message) || err || '') };
   }
+  const status = readRunnerStatus(result);
   let brief = null;
-  let ok = status === 0;
+  let lesson = null;
+  let ok = status === 0 || keptPrintedNotes({
+    url: item.url,
+    workDir: notesWorkDir(deps),
+    result,
+  });
   if (ok && deps.save) {
     const saved = saveRichNotes(item.url, deps);
     if (saved.thin) {
@@ -1455,6 +1873,7 @@ function runOneNotesItem(item, engine, deps = {}) {
       ok = false;
     } else {
       brief = saved.brief;
+      lesson = saved.lesson;
       const ensureApply = deps.ensureApply || ensureNotesApply;
       try {
         ensureApply({
@@ -1471,7 +1890,7 @@ function runOneNotesItem(item, engine, deps = {}) {
   }
   const seconds = Math.max(0, Math.round((readNowMs(deps) - started) / 1000));
   output(`${label}  ${seconds}s  ${ok ? (brief || 'ok') : 'FAILED'}`);
-  return { url: item.url, id: item.id, seconds, ok, brief };
+  return { url: item.url, id: item.id, seconds, ok, brief, lesson };
 }
 
 function formatNotesSummary(rows = []) {
@@ -1483,7 +1902,14 @@ function formatNotesSummary(rows = []) {
   return lines.join('\n');
 }
 
-function runYoutubeNotesBatch({ urls, engine, save } = {}, deps = {}) {
+function printEphemeralNotesLearnerGate(url, { json = false, workDir } = {}, output) {
+  const dir = workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
+  const lesson = notesLessonFromText(readNotesText({ url, workDir: dir }));
+  if (!isThinTeachLesson(lesson)) applyGate.hintEphemeralApply(output, 'notes');
+  printLearnerCheckGate(output, lesson, { includeCheck: true, json });
+}
+
+function runYoutubeNotesBatch({ urls, engine, save, json } = {}, deps = {}) {
   deps = { ...deps, save: save === true || deps.save === true };
   const output = deps.output || ((line = '') => console.error(line));
   const items = expandNotesTargets(urls || [], deps);
@@ -1496,7 +1922,30 @@ function runYoutubeNotesBatch({ urls, engine, save } = {}, deps = {}) {
     output(formatNotesSummary(rows));
   }
   if (!rows.length) return 2;
-  return rows.some((row) => row.ok) ? 0 : 2;
+  const firstOk = rows.find((row) => row.ok);
+  const asJson = json === true || deps.json === true;
+  if (firstOk && !deps.save) {
+    if (!asJson) printEphemeralNotesLearnerGate(firstOk.url, { workDir: deps.workDir }, output);
+    printYoutubeTeachNext(firstOk.url, { json: asJson }, output);
+  }
+  if (firstOk && deps.save) {
+    if (deps.ensureApply) return 0;
+    const id = firstOk.id || videoIdFromUrl(firstOk.url);
+    const workDir = deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
+    const lesson = firstOk.lesson || notesLessonFromText(readNotesText({
+      url: firstOk.url,
+      workDir,
+    }));
+    const baseline = proveSavedLearnerBaseline({
+      cwd: deps.cwd || process.cwd(),
+      applyRel: id ? applySidecarRel(id) : null,
+      lesson,
+      output,
+      json: asJson,
+    });
+    if (baseline !== 0) return baseline;
+  }
+  return firstOk ? 0 : 2;
 }
 
 function runSingleYoutubeNotes(url, engine, deps = {}) {
@@ -1504,30 +1953,49 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
   try {
     result = invokeNotesRunner(url, engine, deps);
   } catch {
-    return 1;
+    result = { status: 1 };
   }
   const status = readRunnerStatus(result);
-  if (status !== 0) return status;
+  if (status !== 0 && !keptPrintedNotes({
+    url,
+    workDir: notesWorkDir(deps),
+    result,
+  })) {
+    return status == null ? 1 : status;
+  }
   const output = deps.output || ((line = '') => console.error(line));
   if (!deps.save) {
-    const workDir = deps.workDir || path.join(process.env.TMPDIR || '/tmp', 'ytnotes');
-    const lesson = notesLessonFromText(readNotesText({ url, workDir }));
-    if (!isThinTeachLesson(lesson)) applyGate.hintEphemeralApply(output, 'notes');
+    const json = deps.json === true;
+    printEphemeralNotesLearnerGate(url, { json, workDir: deps.workDir }, output);
+    printYoutubeTeachNext(url, { json }, output);
     return 0;
   }
   const saved = saveRichNotes(url, deps);
   if (saved.thin) {
     output(TEACH_THIN_REFUSE);
+    printYoutubeTeachNext(url, { json: deps.json }, output);
     return 2;
   }
   const ensureApply = deps.ensureApply || ensureNotesApply;
-  return ensureApply({
-    cwd: deps.cwd || process.cwd(),
+  const cwd = deps.cwd || process.cwd();
+  const applyCode = ensureApply({
+    cwd,
     url,
     packRel: saved.packRel,
     now: deps.now,
     output: deps.output,
   });
+  if (deps.ensureApply) return applyCode;
+  const id = videoIdFromUrl(url);
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: id ? applySidecarRel(id) : null,
+    lesson: saved.lesson,
+    output,
+    json: deps.json === true,
+  });
+  if (baseline !== 0) return baseline;
+  return applyCode;
 }
 
 function runYoutubeNotes(args = [], deps = {}) {
@@ -1545,7 +2013,7 @@ function runYoutubeNotes(args = [], deps = {}) {
     output(YTNOTES_HINT);
     return 2;
   }
-  const nextDeps = { ...deps, save: parsed.save };
+  const nextDeps = { ...deps, save: parsed.save, json: parsed.json };
   if (parsed.urls.length === 1 && !isPlaylistUrl(parsed.urls[0])) {
     return runSingleYoutubeNotes(parsed.urls[0], parsed.engine, nextDeps);
   }
@@ -1575,11 +2043,14 @@ function showYoutubeSearchHelp(output = console.log, commandName = 'atris youtub
   output('');
   output('Free local discovery. Uses ytsearch on PATH when present, else the');
   output('bundled scripts/det/ytsearch, else yt-dlp ytsearchN with the same print contract.');
-  output('Does not bill credits. Process stays the 5-credit step after you pick a URL.');
+  output('Does not bill credits. A thin hit prints check: fill this and one next: atris youtube teach <first-url>.');
+  output('A rich hit writes one apply and a failing keep/revert pack (score 0).');
   output('');
   output(`--paid buys watch permalinks from Atris (${PAID_SEARCH_COST_HINT}).`);
   output('Requires login. Same auth path as atris youtube process.');
-  output('Empty or failed paid search refunds the credits.');
+  output('A rich hit writes one apply and a failing keep/revert pack (score 0).');
+  output('A thin hit prints check: fill this and one next: atris youtube teach <first-url>.');
+  output('Empty or failed paid search prints credits refunded only when the server marks a refund.');
   output('');
   output('Options:');
   output(`  --limit <n>         Max results (default: ${DEFAULT_SEARCH_LIMIT})`);
@@ -1709,6 +2180,17 @@ function resolveSearchCachePath(deps = {}) {
   return path.join(homeDir, '.atris', LOCAL_SEARCH_CACHE_FILE);
 }
 
+function printYoutubeTeachNext(url, options, output) {
+  if (options && options.json) return;
+  if (!url) return;
+  output(`next: atris youtube teach ${quoteYoutubeUrl(url)}`);
+}
+
+function printSearchTeachNext(rows, options, output) {
+  const firstUrl = Array.isArray(rows) && rows[0] && rows[0].url;
+  printYoutubeTeachNext(firstUrl, options, output);
+}
+
 function printSearchRows(rows, options, output) {
   if (options.json) {
     output(JSON.stringify(rows, null, 2));
@@ -1813,9 +2295,8 @@ function paidSearchCredits(data) {
   return { used, remaining, refunded };
 }
 
-function creditsWereRefunded(credits) {
+function creditsRefundedExplicitly(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;
 }
@@ -1825,7 +2306,7 @@ function formatCreditsLines(credits) {
   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)) {
+  if (creditsRefundedExplicitly(credits)) {
     lines.push('credits refunded');
   }
   return lines;
@@ -1852,7 +2333,7 @@ function youtubeSearchFailureError(result) {
         ? ' YouTube search is unavailable; retry in a few seconds.'
         : '';
   const credits = paidSearchCredits(result.data);
-  const refundHint = result.status === 502 && creditsWereRefunded(credits)
+  const refundHint = result.status === 502 && creditsRefundedExplicitly(credits)
     ? ' credits refunded.'
     : '';
   const lines = [`YouTube search failed (${result.status}): ${resultErrorText(result)}.${hint}${refundHint}`];
@@ -1881,6 +2362,12 @@ async function requestPaidYoutubeSearch(options, deps = {}) {
   if (!result.ok && result.status === 401 && !auth.minted) {
     const remint = await ensureBilled('youtube', { ...deps, forceMint: true });
     if (remint?.ok && remint.token) {
+      if (!options.json) {
+        const print = typeof deps.output === 'function' ? deps.output : () => {};
+        for (const line of formatCreditsLines(paidSearchCredits(result.data))) {
+          print(line);
+        }
+      }
       auth = remint;
       result = await call(auth.token);
     }
@@ -1908,10 +2395,146 @@ async function runPaidYoutubeSearch(options, deps = {}) {
   const rendered = formatPaidSearchResults(data);
   if (!videos.length) {
     output(rendered ? `no videos found\n${rendered}` : 'no videos found');
+    printWatchTickNext(output);
     return 2;
   }
   output(rendered);
-  return 0;
+  return gateSearchLearner(videos, options, output, deps);
+}
+
+function searchLessonText(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .map((row) => String(row && row.title ? row.title : '').trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function searchExperimentSlug(query) {
+  return `search-${applyGate.applySlug(query)}`;
+}
+
+function searchExperimentRel(query) {
+  return `atris/experiments/${searchExperimentSlug(query)}`;
+}
+
+function searchApplyRel(query) {
+  return applyGate.applySidecarRel('search', applyGate.applySlug(query));
+}
+
+function searchApplyNow(now) {
+  if (typeof now === 'function') {
+    const value = now();
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) return value;
+    const ms = Number(value);
+    if (Number.isFinite(ms) && ms > 0) return new Date(ms).toISOString().slice(0, 10);
+    return undefined;
+  }
+  return now;
+}
+
+function saveRichSearch({ cwd, query, lesson } = {}) {
+  if (isThinTeachLesson(lesson)) {
+    return { thin: true, packRel: null, lesson };
+  }
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  const packRel = fileTeachExperiment({
+    cwd,
+    lesson,
+    slug: query ? searchExperimentSlug(query) : null,
+    applyRel: query ? searchApplyRel(query) : null,
+  });
+  return { thin: false, packRel, lesson, source: query };
+}
+
+function ensureSearchApply({ cwd, query, packRel, now, output, source } = {}) {
+  const pack = packRel || (query ? searchExperimentRel(query) : null);
+  const slug = pack ? path.basename(pack) : null;
+  if (cwd) fs.mkdirSync(path.join(cwd, 'atris', 'wiki'), { recursive: true });
+  return applyGate.ensureApply({
+    cwd,
+    source: source || query || 'search',
+    rel: query ? searchApplyRel(query) : null,
+    now,
+    output,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : applyGate.ephemeralApplyMessage('search'),
+    required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
+  });
+}
+
+function mintRichSearch({ cwd, query, rows, now, output, ensureApply, json } = {}) {
+  const print = typeof output === 'function' ? output : (line = '') => console.log(line);
+  const lesson = notesLessonFromText(searchLessonText(rows));
+  if (json) return { thin: false, code: 0, lesson };
+  if (isThinTeachLesson(lesson)) {
+    printSearchLearnerGate(rows, { json: false }, print);
+    return { thin: true, code: 0, lesson };
+  }
+  const saved = saveRichSearch({ cwd, query, lesson });
+  const applyFn = ensureApply || ensureSearchApply;
+  const applyCode = applyFn({
+    cwd,
+    query,
+    packRel: saved.packRel,
+    now: searchApplyNow(now),
+    output: print,
+    source: query,
+  });
+  if (ensureApply) return { thin: false, code: applyCode, lesson: saved.lesson };
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: query ? searchApplyRel(query) : null,
+    lesson: saved.lesson,
+    output: print,
+    json,
+  });
+  if (baseline !== 0) return { thin: false, code: baseline, lesson: saved.lesson };
+  return { thin: false, code: applyCode, lesson: saved.lesson };
+}
+
+function printSearchLearnerGate(rows, options, output) {
+  printLearnerCheckGate(output, notesLessonFromText(searchLessonText(rows)), {
+    includeCheck: true,
+    json: Boolean(options && options.json),
+  });
+}
+
+function gateSearchLearner(rows, options, output, deps = {}) {
+  if (options && options.json) return 0;
+  const minted = mintRichSearch({
+    cwd: deps.cwd || process.cwd(),
+    query: options && options.query,
+    rows,
+    now: deps.now,
+    output,
+    ensureApply: deps.ensureApply,
+    json: false,
+  });
+  if (minted.thin) printSearchTeachNext(rows, options, output);
+  return minted.code;
+}
+
+function printSearchOutcome(rows, options, output, deps = {}) {
+  printSearchRows(rows, options, output);
+  return gateSearchLearner(rows, options, output, deps);
+}
+
+function resultStdout(result) {
+  if (typeof result === 'string') return result;
+  return String((result && result.stdout) || '');
+}
+
+function searchRowsFromResult(result) {
+  return parseSearchStdout(resultStdout(result));
+}
+
+function finishSuccessfulSearch(rows, options, output, deps) {
+  writeLocalSearchCache(options.query, rows, deps);
+  return printSearchOutcome(rows, options, output, deps);
 }
 
 function commandOnPath(name, deps = {}) {
@@ -2030,6 +2653,9 @@ async function runYoutubeSearch(args = [], deps = {}) {
     return 2;
   }
 
+  let rows = searchRowsFromResult(result);
+  if (rows.length) return finishSuccessfulSearch(rows, options, output, deps);
+
   let status = searchRunnerStatus(result);
   if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
     await waitLocalSearchBackoff(deps);
@@ -2043,14 +2669,16 @@ async function runYoutubeSearch(args = [], deps = {}) {
       output('ytsearch and yt-dlp not found. Install yt-dlp or put ytsearch on PATH.');
       return 2;
     }
+    rows = searchRowsFromResult(result);
+    if (rows.length) return finishSuccessfulSearch(rows, options, output, deps);
     status = searchRunnerStatus(result);
     if (status != null && status !== 0 && isLocalSearchRateLimited(result)) {
       const cached = readFreshLocalSearchCache(options.query, deps);
       if (cached) {
-        const rows = cached.rows.slice(0, options.limit);
-        printSearchRows(rows, options, output);
+        const cachedRows = cached.rows.slice(0, options.limit);
+        const code = printSearchOutcome(cachedRows, options, output, deps);
         output(LOCAL_SEARCH_CACHE_NOTE);
-        return 0;
+        return code;
       }
       output(LOCAL_SEARCH_RATE_LIMIT_MESSAGE);
       return status == null ? 1 : status;
@@ -2063,23 +2691,20 @@ async function runYoutubeSearch(args = [], deps = {}) {
     return status == null ? 1 : status;
   }
 
-  const stdout = typeof result === 'string' ? result : String((result && result.stdout) || '');
-  const rows = parseSearchStdout(stdout);
-  if (!rows.length) {
-    output('no videos found');
-    return 2;
-  }
-
-  writeLocalSearchCache(options.query, rows, deps);
-  printSearchRows(rows, options, output);
-  return 0;
+  output('no videos found');
+  if (!options.json) printWatchTickNext(output);
+  return 2;
 }
 
-const YTTEACH_USAGE = 'usage: atris youtube teach <youtube-url> [--section N] [--save] [--recap TEXT] [--skip]';
+const YTTEACH_USAGE = 'usage: atris youtube teach <youtube-url> [--section N] [--save] [--recap TEXT] [--skip] | owed | next';
 const TEACH_PAID_REFUSE = 'teach is free local captions. drop --paid.';
 const TEACH_THIN_REFUSE = 'thin: no number or named mechanism. no brief.';
 const TEACH_OWED_FILE = 'youtube-teach-owed.json';
 const TEACH_RECAP_MISSING = '--recap needs the unpaid check';
+const TEACH_RESUME_START = 'atris youtube teach <url>';
+const TEACH_RESUME_NEXT = 'next: atris youtube teach recap TEXT or atris youtube teach skip';
+const TEACH_WATCH_TICK_NEXT = WATCH_TICK_NEXT;
+const TEACH_CONTINUE_NEXT = 'next: atris youtube teach next';
 const TEACH_APPLY_NEXT_MESSAGE = APPLY_NEXT_MESSAGE;
 const TEACH_KEEP_RULE = 'keep only if measure.py moves 0→1. scores 1 only when the fixture contains the check tokens.';
 const MECHANISM_STOP = new Set([
@@ -2108,12 +2733,16 @@ function parseTeachArgs(argv = []) {
     save: false,
     json: false,
     skip: false,
+    owed: false,
+    resume: false,
+    next: false,
     recap: null,
     url: null,
     section: 1,
   };
+  let sectionSet = false;
 
-  if (args.length === 0 || ['help', '--help', '-h'].includes(args[0])) {
+  if (args.length > 0 && ['help', '--help', '-h'].includes(args[0])) {
     options.help = true;
     return options;
   }
@@ -2128,6 +2757,8 @@ function parseTeachArgs(argv = []) {
       options.json = true;
     } else if (arg === '--skip') {
       options.skip = true;
+    } else if (arg === '--owed') {
+      options.owed = true;
     } else if (arg === '--paid') {
       throw new Error(TEACH_PAID_REFUSE);
     } else if (arg === '--recap') {
@@ -2148,6 +2779,7 @@ function parseTeachArgs(argv = []) {
         throw new Error('--section must be a positive integer');
       }
       options.section = value;
+      sectionSet = true;
       i += 1;
     } else if (arg.startsWith('--section=')) {
       const value = Number.parseInt(arg.slice('--section='.length), 10);
@@ -2155,6 +2787,7 @@ function parseTeachArgs(argv = []) {
         throw new Error('--section must be a positive integer');
       }
       options.section = value;
+      sectionSet = true;
     } else if (arg.startsWith('-')) {
       throw new Error(`Unknown option: ${arg}`);
     } else if (arg === 'recap' && options.recap == null && !options.url) {
@@ -2169,6 +2802,10 @@ function parseTeachArgs(argv = []) {
       if (!options.recap) throw new Error(TEACH_RECAP_MISSING);
     } else if (arg === 'skip' && !options.url) {
       options.skip = true;
+    } else if (arg === 'owed' && !options.url) {
+      options.owed = true;
+    } else if (arg === 'next' && !options.url) {
+      options.next = true;
     } else if (!options.url && looksLikeYoutubeUrl(arg)) {
       options.url = arg;
     } else {
@@ -2177,7 +2814,12 @@ function parseTeachArgs(argv = []) {
   }
 
   if (options.help) return options;
-  if (!options.url && options.recap == null && !options.skip) {
+  if (!options.url && options.recap == null && !options.skip && !options.owed && !options.next) {
+    if (!sectionSet && !options.save) {
+      options.owed = true;
+      options.resume = true;
+      return options;
+    }
     throw new Error('Missing YouTube URL. Run "atris youtube teach --help".');
   }
   return options;
@@ -2297,7 +2939,13 @@ function extractTeachMechanisms(text) {
   return found.slice(0, 8);
 }
 
-function oneTeachCheck(mechanisms, numbers, title) {
+const LEARNER_CHECK_FILL = 'fill this';
+const LEARNER_SCORE_ZERO = 'score: 0';
+const LEARNER_CHECK_INCOMPLETE = 'incomplete: no measurable check. check: fill this';
+const LEARNER_BASELINE_INCOMPLETE = 'incomplete: check already passes. refuse invented success.';
+const LEARNER_APPLY_MISSING = 'incomplete: apply missing. check cannot score.';
+
+function oneTeachCheck(mechanisms, numbers) {
   if (mechanisms[0]) {
     const name = mechanisms[0];
     const named = new RegExp(`\\b(?:${MECHANISM_HEADS})\\b`, 'i').test(name);
@@ -2305,7 +2953,63 @@ function oneTeachCheck(mechanisms, numbers, title) {
     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'}?`;
+  return LEARNER_CHECK_FILL;
+}
+
+function learnerCheckFromLesson(lesson = {}) {
+  const mechanisms = Array.isArray(lesson.mechanisms) ? lesson.mechanisms : [];
+  const numbers = Array.isArray(lesson.numbers) ? lesson.numbers : [];
+  const inferred = mechanisms.length > 0 || numbers.length > 0;
+  return {
+    inferred,
+    line: inferred ? oneTeachCheck(mechanisms, numbers) : LEARNER_CHECK_FILL,
+    needles: teachCheckNeedles({ mechanisms, numbers }),
+  };
+}
+
+function scoreLearnerNeedles(text, needles) {
+  const list = Array.isArray(needles) ? needles : [];
+  if (!list.length) return 0;
+  const blob = String(text || '').toLowerCase();
+  return list.every((needle) => blob.includes(String(needle || '').toLowerCase())) ? 1 : 0;
+}
+
+function printLearnerCheckGate(output, lesson, { includeCheck = false, json = false } = {}) {
+  if (json || typeof output !== 'function') return;
+  const check = learnerCheckFromLesson(lesson);
+  if (includeCheck) output(`check: ${check.line}`);
+  if (check.inferred) output(LEARNER_SCORE_ZERO);
+}
+
+function proveSavedLearnerBaseline({ cwd, applyRel, lesson, output, json } = {}) {
+  const print = typeof output === 'function' ? output : () => {};
+  const check = learnerCheckFromLesson(lesson);
+  if (!check.inferred) {
+    if (!json) print(LEARNER_CHECK_INCOMPLETE);
+    return 2;
+  }
+  if (!cwd || !applyRel) {
+    if (!json) print(LEARNER_APPLY_MISSING);
+    return 2;
+  }
+  const abs = path.join(cwd, applyRel);
+  let text = '';
+  try {
+    if (!fs.existsSync(abs)) {
+      if (!json) print(LEARNER_APPLY_MISSING);
+      return 2;
+    }
+    text = fs.readFileSync(abs, 'utf8');
+  } catch {
+    if (!json) print(LEARNER_APPLY_MISSING);
+    return 2;
+  }
+  if (scoreLearnerNeedles(text, check.needles) !== 0) {
+    if (!json) print(LEARNER_BASELINE_INCOMPLETE);
+    return 2;
+  }
+  if (!json) print(LEARNER_SCORE_ZERO);
+  return 0;
 }
 
 function quoteYoutubeUrl(url) {
@@ -2336,10 +3040,7 @@ function teachLessonFromCues({ url, section, chapters, chapter, cues, title } =
   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');
+    lines.push(TEACH_RESUME_NEXT);
   }
   return { text: lines.join('\n'), numbers, mechanisms };
 }
@@ -2429,32 +3130,136 @@ function writeTeachOwedStore(deps, store) {
   }
 }
 
-function rememberTeachOwed(deps, { url, section, lesson } = {}) {
+function rememberTeachOwed(deps, { url, section, lesson, total } = {}) {
   const id = videoIdFromUrl(url);
   if (!id) return;
   const store = readTeachOwedStore(deps);
-  store[id] = {
+  const row = {
     section: Number(section) || 1,
     check: teachCheckLine(lesson),
     tokens: teachRecapTokens(lesson),
+    url: url || undefined,
   };
+  const totalChapters = Number(total);
+  if (Number.isInteger(totalChapters) && totalChapters > 0) row.total = totalChapters;
+  store[id] = row;
   writeTeachOwedStore(deps, store);
 }
 
+function writeTeachContinue(store, id, entry) {
+  const nextSection = (Number(entry && entry.section) || 1) + 1;
+  const total = Number(entry && entry.total);
+  if (Number.isInteger(total) && total > 0 && nextSection > total) {
+    delete store[id];
+    return null;
+  }
+  const cursor = {
+    section: nextSection,
+    url: (entry && entry.url) || undefined,
+  };
+  if (Number.isInteger(total) && total > 0) cursor.total = total;
+  store[id] = cursor;
+  return cursor;
+}
+
+function lastTeachContinueEntry(store) {
+  const ids = Object.keys(store || {});
+  for (let i = ids.length - 1; i >= 0; i -= 1) {
+    const entry = store[ids[i]];
+    if (!entry || typeof entry !== 'object') continue;
+    if (String(entry.check || '').trim()) continue;
+    const url = String(entry.url || '').trim();
+    if (!url) continue;
+    return {
+      id: ids[i],
+      url,
+      section: Number(entry.section) || 1,
+    };
+  }
+  return null;
+}
+
+function lastTeachUnpaidEntry(store) {
+  const ids = Object.keys(store || {});
+  for (let i = ids.length - 1; i >= 0; i -= 1) {
+    const entry = store[ids[i]];
+    if (!entry || typeof entry !== 'object') continue;
+    const check = String(entry.check || '').trim();
+    if (!check) continue;
+    return {
+      id: ids[i],
+      check,
+      url: entry.url || null,
+      section: Number(entry.section) || 1,
+    };
+  }
+  return null;
+}
+
 function previousTeachUnlocked(owed, section) {
   if (!owed) return true;
   return Number(owed.section) >= Number(section);
 }
 
+function printTeachUnlockNext(parsed, entry, output) {
+  if (!parsed || parsed.json) return;
+  const url = parsed.url || (entry && entry.url) || '';
+  if (!url) return;
+  output(TEACH_CONTINUE_NEXT);
+}
+
+function printTeachWatchTickNext(parsed, lesson, total, output) {
+  if (!parsed || parsed.json) return;
+  if (parsed.save && !isThinTeachLesson(lesson)) return;
+  const section = Number(parsed.section) || 0;
+  if (section < Number(total)) return;
+  printWatchTickNext(output);
+}
+
+function listTeachOwedEntries(store) {
+  return Object.keys(store || {}).map((id) => {
+    const entry = store[id] && typeof store[id] === 'object' ? store[id] : {};
+    return {
+      id,
+      url: entry.url || null,
+      section: Number(entry.section) || 1,
+      check: String(entry.check || '').trim(),
+    };
+  }).filter((row) => row.check);
+}
+
+function printTeachOwed(parsed, deps, output) {
+  const rows = listTeachOwedEntries(readTeachOwedStore(deps));
+  if (parsed.json) {
+    output(JSON.stringify(rows));
+    return 0;
+  }
+  if (!rows.length) {
+    output('nothing owed');
+    if (parsed.resume) output(TEACH_RESUME_START);
+    return 0;
+  }
+  rows.forEach((row, index) => {
+    if (index) output('');
+    output(row.url || row.id);
+    output(`section ${row.section}`);
+    if (row.check) output(row.check);
+  });
+  if (parsed.resume) output(TEACH_RESUME_NEXT);
+  return 0;
+}
+
 function applyTeachRecap(parsed, deps, output) {
   const store = readTeachOwedStore(deps);
   let id = parsed.url ? videoIdFromUrl(parsed.url) : null;
   let entry = id ? store[id] : null;
   if (!entry && !id) {
     const ids = Object.keys(store);
+    const unpaidIds = ids.filter((key) => store[key] && String(store[key].check || '').trim());
     if (parsed.recap) {
-      id = ids.find((key) => recapHitsTokens(parsed.recap, store[key] && store[key].tokens));
+      id = unpaidIds.find((key) => recapHitsTokens(parsed.recap, store[key] && store[key].tokens));
     }
+    if (!id && unpaidIds.length === 1) id = unpaidIds[0];
     if (!id && ids.length === 1) id = ids[0];
     entry = id ? store[id] : null;
   }
@@ -2463,8 +3268,13 @@ function applyTeachRecap(parsed, deps, output) {
     if (!parsed.json) output('recap the previous section first');
     return 2;
   }
+  if (!String(entry.check || '').trim()) {
+    printTeachUnlockNext(parsed, entry, output);
+    return 0;
+  }
   if (parsed.skip) {
-    delete store[id];
+    printTeachUnlockNext(parsed, entry, output);
+    writeTeachContinue(store, id, entry);
     writeTeachOwedStore(deps, store);
     return 0;
   }
@@ -2472,11 +3282,40 @@ function applyTeachRecap(parsed, deps, output) {
     if (!parsed.json) output(entry.check);
     return 2;
   }
-  delete store[id];
+  printTeachUnlockNext(parsed, entry, output);
+  writeTeachContinue(store, id, entry);
   writeTeachOwedStore(deps, store);
   return 0;
 }
 
+function applyTeachNext(parsed, deps, output) {
+  const store = readTeachOwedStore(deps);
+  const cont = lastTeachContinueEntry(store);
+  if (cont) {
+    parsed.url = cont.url;
+    parsed.section = cont.section;
+    return 0;
+  }
+  const unpaid = lastTeachUnpaidEntry(store);
+  if (unpaid) {
+    if (!parsed.json) output(unpaid.check);
+    return 2;
+  }
+  if (parsed.json) {
+    output('[]');
+    return 0;
+  }
+  output('nothing owed');
+  output(TEACH_RESUME_START);
+  return 0;
+}
+
+function applyTeachResume(parsed, deps, output) {
+  const store = readTeachOwedStore(deps);
+  if (lastTeachUnpaidEntry(store)) return printTeachOwed(parsed, deps, output);
+  return applyTeachNext(parsed, deps, output);
+}
+
 function teachCheckLine(lesson = {}) {
   return oneTeachCheck(lesson.mechanisms || [], lesson.numbers || [], '');
 }
@@ -2765,14 +3604,15 @@ function fileTeachBrief({ cwd, url, section, lesson, now } = {}) {
 function ensureTeachApply({ cwd, url, section, packRel, now, output } = {}) {
   const id = videoIdFromUrl(url);
   const pack = packRel || (id ? teachExperimentRel(id, section) : null);
+  const slug = pack ? path.basename(pack) : null;
   return applyGate.ensureApply({
     cwd,
     source: url,
     rel: id ? applySidecarRel(`${id}-s${section}`) : null,
     now,
     output,
-    incompleteMessage: pack
-      ? `next: apply ${pack}. keep only if measure.py moves 0→1`
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
       : TEACH_APPLY_NEXT_MESSAGE,
     required: false,
     change: pack ? `apply ${pack}` : undefined,
@@ -2786,33 +3626,23 @@ async function extractTeachSource(youtubeUrl, deps = {}) {
     return deps.extractTeachSource(youtubeUrl, deps);
   }
   const runner = deps.spawnSync || spawnSync;
-  const result = runner('yt-dlp', ['-J', '--skip-download', '--no-warnings', youtubeUrl], {
+  const result = runner('yt-dlp', ytDlpInfoArgs(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);
+  const info = parseYtDlpInfoJson(result);
+  const loaded = await loadCaptionRaw(info, youtubeUrl, deps);
+  const cues = parseCaptionCues(loaded && loaded.raw);
   if (!cues.length) return null;
 
   return {
-    id: info.id || videoIdFromUrl(youtubeUrl),
-    title: info.title || '',
+    id: teachSourceVideoId(info, youtubeUrl),
+    title: (info && info.title) || '',
     url: youtubeUrl,
-    durationSeconds: Number(info.duration || 0) || undefined,
-    language: selected.language || 'unknown',
-    chapters: normalizeChapters(info.chapters, info.duration),
+    durationSeconds: Number((info && info.duration) || 0) || undefined,
+    language: loaded.language || 'unknown',
+    chapters: normalizeChapters(info && info.chapters, info && info.duration),
     cues,
   };
 }
@@ -2832,11 +3662,22 @@ async function runYoutubeTeach(args = [], deps = {}) {
   }
 
   const owedDeps = { ...deps, cwd: deps.cwd || process.cwd() };
+  if (parsed.owed) {
+    if (!parsed.resume) return printTeachOwed(parsed, owedDeps, output);
+    const resumeCode = applyTeachResume(parsed, owedDeps, output);
+    if (resumeCode !== 0) return resumeCode;
+    if (!parsed.url) return 0;
+  }
   if (parsed.recap != null || parsed.skip) {
     const recapCode = applyTeachRecap(parsed, owedDeps, output);
     if (recapCode !== 0) return recapCode;
     if (!parsed.url || parsed.section <= 1) return 0;
   }
+  if (parsed.next) {
+    const nextCode = applyTeachNext(parsed, owedDeps, output);
+    if (nextCode !== 0) return nextCode;
+    if (!parsed.url) return 0;
+  }
 
   if (!parsed.url) {
     output('Missing YouTube URL. Run "atris youtube teach --help".');
@@ -2851,7 +3692,10 @@ async function runYoutubeTeach(args = [], deps = {}) {
     }
   }
 
-  const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, deps);
+  const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, {
+    ...deps,
+    workDir: deps.workDir || notesWorkDir(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;
@@ -2874,39 +3718,59 @@ async function runYoutubeTeach(args = [], deps = {}) {
     title: source.title,
   });
   output(lesson.text);
-  rememberTeachOwed(owedDeps, { url: parsed.url, section: parsed.section, lesson });
+  rememberTeachOwed(owedDeps, {
+    url: parsed.url,
+    section: parsed.section,
+    lesson,
+    total: chapters.length,
+  });
 
   if (!parsed.save) {
     if (!isThinTeachLesson(lesson)) applyGate.hintEphemeralApply(output, 'teach');
+    printLearnerCheckGate(output, lesson, { includeCheck: true, json: parsed.json === true });
+    printTeachWatchTickNext(parsed, lesson, chapters.length, output);
     return 0;
   }
   if (isThinTeachLesson(lesson)) {
     output(TEACH_THIN_REFUSE);
+    printTeachWatchTickNext(parsed, lesson, chapters.length, output);
     return 2;
   }
 
+  const cwd = deps.cwd || process.cwd();
   fileTeachBrief({
-    cwd: deps.cwd || process.cwd(),
+    cwd,
     url: parsed.url,
     section: parsed.section,
     lesson: lesson.text,
     now: deps.now,
   });
   const packRel = fileTeachExperiment({
-    cwd: deps.cwd || process.cwd(),
+    cwd,
     url: parsed.url,
     section: parsed.section,
     lesson,
   });
   const ensureApply = deps.ensureApply || ensureTeachApply;
-  return ensureApply({
-    cwd: deps.cwd || process.cwd(),
+  const applyCode = ensureApply({
+    cwd,
     url: parsed.url,
     section: parsed.section,
     packRel,
     now: deps.now,
     output,
   });
+  if (deps.ensureApply) return applyCode;
+  const id = videoIdFromUrl(parsed.url);
+  const baseline = proveSavedLearnerBaseline({
+    cwd,
+    applyRel: id ? applySidecarRel(`${id}-s${parsed.section}`) : null,
+    lesson,
+    output,
+    json: parsed.json === true,
+  });
+  if (baseline !== 0) return baseline;
+  return applyCode;
 }
 
 async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
@@ -2951,7 +3815,20 @@ async function youtubeCommand(argv = process.argv.slice(3), deps = {}) {
   let status = 0;
   try {
     const data = await processYoutube(options, deps);
-    output(options.json ? JSON.stringify(data, null, 2) : formatYoutubeResult(data));
+    if (options.json) {
+      output(JSON.stringify(data, null, 2));
+    } else {
+      output(formatYoutubeResult(data));
+      const mintCode = mintRichProcess({
+        cwd: deps.cwd || process.cwd(),
+        url: options.youtubeUrl,
+        data,
+        now: deps.now,
+        output,
+        ensureApply: deps.ensureApply,
+      });
+      if (mintCode !== 0) status = mintCode;
+    }
   } catch (err) {
     if (!err.applyRequired) output(err.message);
     status = Number.isInteger(err.exitCode) ? err.exitCode : 1;
@@ -2968,10 +3845,12 @@ module.exports = {
   parseYoutubeArgs,
   buildYoutubePayload,
   extractLocalTranscript,
+  parseYtDlpInfoJson,
   processYoutube,
   shouldRetryWithLocalTranscript,
   formatYoutubeResult,
   fileBriefFromNotes,
+  keptPrintedNotes,
   ensureNotesApply,
   unsaveYoutubeNotes,
   APPLY_NEXT_MESSAGE,
@@ -2999,10 +3878,27 @@ module.exports = {
   extractTeachNumbers,
   extractTeachMechanisms,
   extractTeachSource,
+  readLocalCaptionText,
+  oneTeachCheck,
+  learnerCheckFromLesson,
+  scoreLearnerNeedles,
+  LEARNER_CHECK_FILL,
+  LEARNER_SCORE_ZERO,
+  printLearnerCheckGate,
+  proveSavedLearnerBaseline,
   isThinTeachLesson,
   TEACH_THIN_REFUSE,
+  TEACH_RESUME_NEXT,
+  TEACH_WATCH_TICK_NEXT,
   teachExperimentSlug,
   notesExperimentSlug,
+  digestExperimentSlug,
+  watchExperimentSlug,
+  processExperimentSlug,
+  processApplyRel,
+  searchExperimentSlug,
+  searchApplyRel,
+  firstRichWatchLesson,
   fileTeachExperiment,
   youtubeCommand,
 };