atris 3.57.3 → 3.58.5

package/commands/youtube.js

@@ -30,7 +30,9 @@ function showYoutubeHelp(output = console.log, commandName = 'atris youtube') {
   output(`Usage: ${commandName} search "<query>" [--limit N] [--json]`);
   output(`       ${commandName} search --paid "<query>" [--limit N] [--json]`);
   output(`       ${commandName} notes <youtube-url> [youtube-url-or-playlist...] [engine] [--save]`);
-  output(`       ${commandName} teach <youtube-url> [--section N] [--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,22 +42,27 @@ 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('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('');
   output('Options:');
   output('  --limit <n>         Max search results (default: 5)');
   output('  --paid              Bill 5 credits for watch permalinks (search only)');
-  output('  --save              File brief, journal, apply stub; teach also mints a keep/revert experiment');
+  output('  --save              File brief, journal, apply; rich notes/teach mint a keep/revert experiment');
   output('  --section <n>       Chapter to teach, 1-based (teach only, default: 1)');
-  output('  --unsave            Delete filed brief and apply stub (no paid calls)');
+  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');
   output('  --store             Save as agent knowledge (requires --agent)');
@@ -74,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`);
@@ -504,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 || {};
@@ -523,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());
@@ -564,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) {
@@ -645,16 +666,69 @@ function applySidecarRel(id) {
   return applyGate.applySidecarRel('youtube', id);
 }
 
-function ensureNotesApply({ cwd, url, now, output } = {}) {
+function notesExperimentSlug(id) {
+  return `notes-${experimentIdToken(id)}`;
+}
+
+function notesExperimentRel(id) {
+  return `atris/experiments/${notesExperimentSlug(id)}`;
+}
+
+function notesLessonFromText(text) {
+  const body = String(text || '');
+  return {
+    numbers: extractTeachNumbers(body),
+    mechanisms: extractTeachMechanisms(body),
+  };
+}
+
+function readNotesText({ url, workDir } = {}) {
+  const id = videoIdFromUrl(url);
+  if (!id || !workDir) return '';
+  const notesPath = path.join(workDir, `yt_${id}.md`);
+  try {
+    if (!fs.existsSync(notesPath)) return '';
+    return fs.readFileSync(notesPath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+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, lesson };
+  }
+  const brief = fileNotesBrief(url, deps);
   const id = videoIdFromUrl(url);
+  const packRel = fileTeachExperiment({
+    cwd: deps.cwd || process.cwd(),
+    url,
+    lesson,
+    slug: id ? notesExperimentSlug(id) : null,
+    applyRel: id ? applySidecarRel(id) : null,
+  });
+  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: APPLY_NEXT_MESSAGE,
+    incompleteMessage: slug
+      ? `next: atris experiments keep ${slug}`
+      : APPLY_NEXT_MESSAGE,
     required: false,
+    change: pack ? `apply ${pack}` : undefined,
+    receipt: pack ? TEACH_KEEP_RULE : undefined,
+    journalLine: pack ? `- [claimable] apply: ${pack}. ${TEACH_KEEP_RULE}` : undefined,
   });
 }
 
@@ -662,6 +736,50 @@ function youtubeBriefRel(id) {
   return `atris/wiki/briefs/youtube-${id}.md`;
 }
 
+function removeUnsaveRel(cwd, rel, removed) {
+  const abs = path.join(cwd, rel);
+  try {
+    if (!fs.existsSync(abs)) return;
+    const st = fs.lstatSync(abs);
+    if (st.isDirectory()) fs.rmSync(abs, { recursive: true, force: true });
+    else fs.unlinkSync(abs);
+    removed.push(rel);
+  } catch {
+    // already gone or unreadable: do not error
+  }
+}
+
+function listTeachSectionNumbers(cwd, id) {
+  const root = path.join(cwd, 'atris', 'experiments');
+  const sections = [];
+  try {
+    if (!fs.existsSync(root)) return sections;
+    for (const name of fs.readdirSync(root)) {
+      const match = String(name).match(/^teach-.+-s(\d+)$/);
+      if (!match) continue;
+      const section = Number(match[1]);
+      if (name === teachExperimentSlug(id, section)) sections.push(section);
+    }
+  } catch {
+    // missing experiments dir is fine
+  }
+  return sections.sort((a, b) => a - b);
+}
+
+function listTeachSidecarRels(cwd, id) {
+  const briefsDir = path.join(cwd, 'atris', 'wiki', 'briefs');
+  const prefix = `youtube-${id}-s`;
+  try {
+    if (!fs.existsSync(briefsDir)) return [];
+    return fs.readdirSync(briefsDir)
+      .filter((name) => name.startsWith(prefix) && name.endsWith('.md'))
+      .sort((a, b) => a.localeCompare(b, 'en'))
+      .map((name) => `atris/wiki/briefs/${name}`);
+  } catch {
+    return [];
+  }
+}
+
 function unsaveYoutubeNotes(target, deps = {}) {
   const output = deps.output || ((line = '') => console.log(line));
   const cwd = deps.cwd || process.cwd();
@@ -672,18 +790,26 @@ function unsaveYoutubeNotes(target, deps = {}) {
   }
   const briefRel = youtubeBriefRel(id);
   const applyRel = applySidecarRel(id);
-  const removed = [];
-  for (const rel of [briefRel, applyRel]) {
-    const abs = path.join(cwd, rel);
-    try {
-      if (fs.existsSync(abs)) {
-        fs.unlinkSync(abs);
-        removed.push(rel);
-      }
-    } catch {
-      // already gone or unreadable: do not error
-    }
+  const sections = listTeachSectionNumbers(cwd, id);
+  const rels = [];
+  const seen = new Set();
+  const add = (rel) => {
+    if (!rel || seen.has(rel)) return;
+    seen.add(rel);
+    rels.push(rel);
+  };
+  add(briefRel);
+  add(applyRel);
+  for (const section of sections) {
+    add(teachBriefRel(id, section));
+    add(applySidecarRel(`${id}-s${section}`));
   }
+  for (const rel of listTeachSidecarRels(cwd, id)) add(rel);
+  add(notesExperimentRel(id));
+  for (const section of sections) add(teachExperimentRel(id, section));
+
+  const removed = [];
+  for (const rel of rels) removeUnsaveRel(cwd, rel, removed);
   if (!removed.length) {
     output(`already gone: ${briefRel} and ${applyRel}`);
     return 0;
@@ -708,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;
 }
 
@@ -870,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;
@@ -889,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;
   }
 
@@ -916,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()) {
@@ -1065,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) {
@@ -1084,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;
   }
 
@@ -1093,6 +1363,7 @@ function addWatchChannel(channelInput, deps = {}) {
   });
   saveWatchState(statePath, state);
   output(`watching ${channel}`);
+  printWatchTickNext(output);
   return 0;
 }
 
@@ -1101,6 +1372,7 @@ function listWatchChannels(deps = {}) {
   const state = loadWatchState(resolveWatchStatePath(deps));
   if (!state.channels.length) {
     output('no channels watched');
+    printWatchAddNext(output);
     return 0;
   }
 
@@ -1108,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;
 }
 
@@ -1124,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;
 }
 
@@ -1141,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);
@@ -1187,6 +1466,7 @@ async function tickWatch(deps = {}) {
       }
       markSeen(state, row.channel, video.id, timestamp);
       briefed += 1;
+      if (!firstBriefedUrl) firstBriefedUrl = url;
     }
 
     if (!isFresh) {
@@ -1204,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;
 }
 
@@ -1339,11 +1653,34 @@ function runOneNotesItem(item, engine, deps = {}) {
   } catch {
     status = 1;
   }
-  const brief = status === 0 && deps.save ? fileNotesBrief(item.url, deps) : null;
+  let brief = null;
+  let lesson = null;
+  let ok = status === 0;
+  if (ok && deps.save) {
+    const saved = saveRichNotes(item.url, deps);
+    if (saved.thin) {
+      output(TEACH_THIN_REFUSE);
+      ok = false;
+    } else {
+      brief = saved.brief;
+      lesson = saved.lesson;
+      const ensureApply = deps.ensureApply || ensureNotesApply;
+      try {
+        ensureApply({
+          cwd: deps.cwd || process.cwd(),
+          url: item.url,
+          packRel: saved.packRel,
+          now: deps.now,
+          output,
+        });
+      } catch {
+        // apply filing must never break the batch
+      }
+    }
+  }
   const seconds = Math.max(0, Math.round((readNowMs(deps) - started) / 1000));
-  const ok = status === 0;
   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 = []) {
@@ -1355,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);
@@ -1368,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 = {}) {
@@ -1380,15 +1747,39 @@ function runSingleYoutubeNotes(url, engine, deps = {}) {
   }
   const status = readRunnerStatus(result);
   if (status !== 0) return status;
-  if (!deps.save) return 0;
-  fileNotesBrief(url, deps);
+  const output = deps.output || ((line = '') => console.error(line));
+  if (!deps.save) {
+    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 = {}) {
@@ -1406,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);
   }
@@ -1436,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:');
@@ -1570,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));
@@ -1769,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)}`], {
@@ -1910,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;
       }
@@ -1928,17 +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]';
+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([
@@ -1965,11 +2397,18 @@ function parseTeachArgs(argv = []) {
   const options = {
     help: false,
     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;
   }
@@ -1980,8 +2419,25 @@ function parseTeachArgs(argv = []) {
       options.help = true;
     } else if (arg === '--save') {
       options.save = true;
+    } else if (arg === '--json') {
+      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') {
+      const raw = args[i + 1];
+      if (raw == null || String(raw).startsWith('--')) {
+        throw new Error(TEACH_RECAP_MISSING);
+      }
+      options.recap = String(raw);
+      i += 1;
+    } else if (arg.startsWith('--recap=')) {
+      const value = arg.slice('--recap='.length);
+      if (!value) throw new Error(TEACH_RECAP_MISSING);
+      options.recap = value;
     } else if (arg === '--section') {
       const raw = args[i + 1];
       const value = Number.parseInt(raw, 10);
@@ -1989,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);
@@ -1996,8 +2453,25 @@ 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) {
+      const parts = [];
+      i += 1;
+      while (i < args.length && !String(args[i]).startsWith('--')) {
+        parts.push(String(args[i]));
+        i += 1;
+      }
+      i -= 1;
+      options.recap = parts.join(' ').trim();
+      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 {
@@ -2006,7 +2480,14 @@ function parseTeachArgs(argv = []) {
   }
 
   if (options.help) return options;
-  if (!options.url) throw new Error('Missing YouTube URL. Run "atris youtube teach --help".');
+  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;
 }
 
@@ -2124,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);
@@ -2132,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) {
@@ -2163,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 };
 }
@@ -2185,14 +2725,17 @@ function teachBriefRel(id, section) {
   return `atris/wiki/briefs/youtube-${id}-s${section}.md`;
 }
 
-function teachExperimentSlug(id, section) {
-  const safe = String(id || 'video')
+function experimentIdToken(id) {
+  return String(id || 'video')
     .toLowerCase()
     .replace(/_/g, '-')
     .replace(/[^a-z0-9-]+/g, '')
     .replace(/-+/g, '-')
     .replace(/^-+|-+$/g, '') || 'video';
-  return `teach-${safe}-s${Number(section) || 1}`;
+}
+
+function teachExperimentSlug(id, section) {
+  return `teach-${experimentIdToken(id)}-s${Number(section) || 1}`;
 }
 
 function teachExperimentRel(id, section) {
@@ -2207,22 +2750,256 @@ function teachCheckNeedles(lesson = {}) {
   return [];
 }
 
+function teachRecapTokens(lesson = {}) {
+  const tokens = [];
+  const seen = new Set();
+  for (const value of [...(lesson.mechanisms || []), ...(lesson.numbers || [])]) {
+    const token = String(value || '').trim().toLowerCase();
+    if (!token || seen.has(token)) continue;
+    seen.add(token);
+    tokens.push(token);
+  }
+  return tokens;
+}
+
+function recapHitsTokens(text, tokens) {
+  const hay = String(text || '').toLowerCase();
+  return (tokens || []).some((token) => {
+    const needle = String(token || '').trim().toLowerCase();
+    return needle.length > 0 && hay.includes(needle);
+  });
+}
+
+function teachOwedPath(deps = {}) {
+  if (deps.teachOwedPath) return deps.teachOwedPath;
+  const cwd = deps.cwd || process.cwd();
+  return path.join(cwd, '.atris', TEACH_OWED_FILE);
+}
+
+function readTeachOwedStore(deps = {}) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(teachOwedPath(deps), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+
+function writeTeachOwedStore(deps, store) {
+  try {
+    const filePath = teachOwedPath(deps);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(store || {})}\n`);
+  } catch {
+    // owed recap is ephemeral; a failed write must not break teach
+  }
+}
+
+function rememberTeachOwed(deps, { url, section, lesson, total } = {}) {
+  const id = videoIdFromUrl(url);
+  if (!id) return;
+  const store = readTeachOwedStore(deps);
+  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 = 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;
+  }
+  if (!entry) {
+    if (parsed.skip) return 0;
+    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) {
+    printTeachUnlockNext(parsed, entry, output);
+    writeTeachContinue(store, id, entry);
+    writeTeachOwedStore(deps, store);
+    return 0;
+  }
+  if (!recapHitsTokens(parsed.recap, entry.tokens)) {
+    if (!parsed.json) output(entry.check);
+    return 2;
+  }
+  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 || [], '');
 }
 
-function fileTeachExperiment({ cwd, url, section, lesson } = {}) {
+function fileTeachExperiment({ cwd, url, section, lesson, slug, applyRel } = {}) {
   try {
-    const id = videoIdFromUrl(url);
-    if (!id || !cwd) return null;
-    const slug = teachExperimentSlug(id, section);
-    const rel = `atris/experiments/${slug}`;
+    const id = url ? videoIdFromUrl(url) : null;
+    if (!cwd) return null;
+    const packSlug = slug || (id ? teachExperimentSlug(id, section) : null);
+    if (!packSlug) return null;
+    const rel = `atris/experiments/${packSlug}`;
     const dir = path.join(cwd, rel);
     fs.mkdirSync(dir, { recursive: true });
 
     const check = teachCheckLine(lesson);
     const needles = teachCheckNeedles(lesson);
-    const applyRel = applySidecarRel(`${id}-s${section}`);
+    const sidecarRel = applyRel || (id ? applySidecarRel(`${id}-s${section}`) : null);
+    if (!sidecarRel) return null;
     const program = [
       '# Program',
       '',
@@ -2243,7 +3020,7 @@ function fileTeachExperiment({ cwd, url, section, lesson } = {}) {
       'EXPERIMENT_DIR = Path(__file__).resolve().parent',
       `CHECK = ${JSON.stringify(check)}`,
       `NEEDLES = ${JSON.stringify(needles)}`,
-      `DEFAULT_TARGET = ${JSON.stringify(applyRel)}`,
+      `DEFAULT_TARGET = ${JSON.stringify(sidecarRel)}`,
       '',
       '',
       'def repo_root() -> Path:',
@@ -2493,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,
@@ -2559,6 +3337,37 @@ async function runYoutubeTeach(args = [], deps = {}) {
     return 0;
   }
 
+  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".');
+    return 2;
+  }
+
+  if (parsed.section > 1) {
+    const owed = readTeachOwedStore(owedDeps)[videoIdFromUrl(parsed.url) || ''];
+    if (!previousTeachUnlocked(owed, parsed.section)) {
+      if (!parsed.json && owed && owed.check) output(owed.check);
+      return 2;
+    }
+  }
+
   const source = await (deps.extractTeachSource || extractTeachSource)(parsed.url, deps);
   if (!source || !Array.isArray(source.cues) || !source.cues.length) {
     output('no english captions for this url. teach stays local and will not call process.');
@@ -2582,35 +3391,59 @@ async function runYoutubeTeach(args = [], deps = {}) {
     title: source.title,
   });
   output(lesson.text);
+  rememberTeachOwed(owedDeps, {
+    url: parsed.url,
+    section: parsed.section,
+    lesson,
+    total: chapters.length,
+  });
 
-  if (!parsed.save) return 0;
+  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 = {}) {
@@ -2655,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;
@@ -2703,8 +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,
 };