atris 3.57.4 → 3.58.5

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 prints one failing check; hands off to teach');
+  output('search --paid = 5 credits, watch permalinks + titles from Atris; rich paid search prints one failing check; 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 prints one failing check');
+  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`);
@@ -507,6 +512,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 || {};
@@ -526,7 +542,7 @@ function formatYoutubeResult(data) {
     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 analysis = processAnalysisText(data);
   if (analysis) {
     lines.push('');
     lines.push(String(analysis).trim());
@@ -567,22 +583,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) {
@@ -680,7 +698,7 @@ 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 +709,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,
@@ -815,6 +834,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;
 }
 
@@ -977,6 +999,104 @@ 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 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 +1116,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 +1144,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()) {
@@ -1172,6 +1318,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 +1353,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 +1363,7 @@ function addWatchChannel(channelInput, deps = {}) {
   });
   saveWatchState(statePath, state);
   output(`watching ${channel}`);
+  printWatchTickNext(output);
   return 0;
 }
 
@@ -1208,6 +1372,7 @@ function listWatchChannels(deps = {}) {
   const state = loadWatchState(resolveWatchStatePath(deps));
   if (!state.channels.length) {
     output('no channels watched');
+    printWatchAddNext(output);
     return 0;
   }
 
@@ -1215,6 +1380,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 +1397,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 +1419,7 @@ async function tickWatch(deps = {}) {
   const state = loadWatchState(statePath);
   let totalNew = 0;
   let totalBriefed = 0;
+  let firstBriefedUrl = null;
 
   for (const row of state.channels) {
     const videosUrl = channelVideosUrl(row.channel);
@@ -1294,6 +1466,7 @@ async function tickWatch(deps = {}) {
       }
       markSeen(state, row.channel, video.id, timestamp);
       briefed += 1;
+      if (!firstBriefedUrl) firstBriefedUrl = url;
     }
 
     if (!isFresh) {
@@ -1311,6 +1484,40 @@ async function tickWatch(deps = {}) {
 
   output(`total: ${totalNew} new, ${totalBriefed} briefed`);
   saveWatchState(statePath, state);
+  if (totalBriefed > 0) {
+    if (firstBriefedUrl) {
+      const lesson = notesLessonFromText(readNotesText({ url: firstBriefedUrl, workDir }));
+      if (isThinTeachLesson(lesson)) {
+        printLearnerCheckGate(output, lesson, { includeCheck: true });
+        printYoutubeTeachNext(firstBriefedUrl, {}, output);
+        return 0;
+      }
+      const saved = saveRichWatch({ cwd, url: firstBriefedUrl, lesson });
+      const ensureApply = deps.ensureApply || ensureWatchApply;
+      const applyCode = ensureApply({
+        cwd,
+        url: firstBriefedUrl,
+        packRel: saved.packRel,
+        now,
+        output,
+        source: firstBriefedUrl,
+      });
+      if (deps.ensureApply) return applyCode;
+      const id = videoIdFromUrl(firstBriefedUrl);
+      const baseline = proveSavedLearnerBaseline({
+        cwd,
+        applyRel: id ? watchApplyRel(id) : null,
+        lesson,
+        output,
+      });
+      if (baseline !== 0) return baseline;
+      return applyCode;
+    }
+    printYoutubeTeachNext(firstBriefedUrl, {}, output);
+    return 0;
+  }
+  if (!state.channels.length) printWatchAddNext(output);
+  else printWatchSearchNext(output);
   return 0;
 }
 
@@ -1447,6 +1654,7 @@ function runOneNotesItem(item, engine, deps = {}) {
     status = 1;
   }
   let brief = null;
+  let lesson = null;
   let ok = status === 0;
   if (ok && deps.save) {
     const saved = saveRichNotes(item.url, deps);
@@ -1455,6 +1663,7 @@ function runOneNotesItem(item, engine, deps = {}) {
       ok = false;
     } else {
       brief = saved.brief;
+      lesson = saved.lesson;
       const ensureApply = deps.ensureApply || ensureNotesApply;
       try {
         ensureApply({
@@ -1471,7 +1680,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 +1692,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 +1712,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 = {}) {
@@ -1510,24 +1749,37 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
   if (status !== 0) return 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 +1797,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,10 +1827,13 @@ 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 hit prints one next: atris youtube teach <first-url>.');
+  output('A rich hit prints one failing check (score 0). A thin hit prints check: fill this.');
   output('');
   output(`--paid buys watch permalinks from Atris (${PAID_SEARCH_COST_HINT}).`);
   output('Requires login. Same auth path as atris youtube process.');
+  output('A hit also prints one next: atris youtube teach <first-url>.');
+  output('A rich hit prints one failing check (score 0). A thin hit prints check: fill this.');
   output('Empty or failed paid search refunds the credits.');
   output('');
   output('Options:');
@@ -1709,6 +1964,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));
@@ -1908,12 +2174,29 @@ 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);
+  printSearchLearnerGate(videos, options, output);
+  printSearchTeachNext(videos, options, output);
   return 0;
 }
 
+function searchLessonText(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .map((row) => String(row && row.title ? row.title : '').trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+function printSearchLearnerGate(rows, options, output) {
+  printLearnerCheckGate(output, notesLessonFromText(searchLessonText(rows)), {
+    includeCheck: true,
+    json: Boolean(options && options.json),
+  });
+}
+
 function commandOnPath(name, deps = {}) {
   const spawn = deps.spawnSync || spawnSync;
   const result = spawn('sh', ['-c', `command -v ${shellSingleQuote(name)}`], {
@@ -2049,6 +2332,7 @@ async function runYoutubeSearch(args = [], deps = {}) {
       if (cached) {
         const rows = cached.rows.slice(0, options.limit);
         printSearchRows(rows, options, output);
+        printSearchTeachNext(rows, options, output);
         output(LOCAL_SEARCH_CACHE_NOTE);
         return 0;
       }
@@ -2067,19 +2351,26 @@ async function runYoutubeSearch(args = [], deps = {}) {
   const rows = parseSearchStdout(stdout);
   if (!rows.length) {
     output('no videos found');
+    if (!options.json) printWatchTickNext(output);
     return 2;
   }
 
   writeLocalSearchCache(options.query, rows, deps);
   printSearchRows(rows, options, output);
+  printSearchLearnerGate(rows, options, output);
+  printSearchTeachNext(rows, options, output);
   return 0;
 }
 
-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 +2399,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 +2423,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 +2445,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 +2453,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 +2468,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 +2480,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 +2605,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 +2619,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 +2706,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 +2796,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 +2934,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 +2948,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 +3270,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,
@@ -2832,11 +3338,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".');
@@ -2874,39 +3391,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 +3488,12 @@ 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));
+      printProcessLearnerGate(data, {}, output);
+    }
   } catch (err) {
     if (!err.applyRequired) output(err.message);
     status = Number.isInteger(err.exitCode) ? err.exitCode : 1;
@@ -2999,10 +3541,21 @@ module.exports = {
   extractTeachNumbers,
   extractTeachMechanisms,
   extractTeachSource,
+  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,
   fileTeachExperiment,
   youtubeCommand,
 };