@fullstackcraftllc/codevideo-mcp 1.1.0 → 1.2.0

package/README.md

@@ -41,28 +41,36 @@ npx @fullstackcraftllc/codevideo-cli doctor
 
 If Chrome is not detected, run `npx @fullstackcraftllc/codevideo-cli install-browser`. `PATH_TO_CODEVIDEO_CLI` remains available as an optional override for local CLI builds.
 
-Simply drop the following into your `claude_desktop_config.json` file:
+Add the server under `mcpServers` in your `claude_desktop_config.json` file, next to any others you have:
 
 ```json
 {
-    // ... other MCP servers
-    "codevideo-mcp": {
-        "command": "npx",
-        "args": [
-            "-y",
-            "@fullstackcraftllc/codevideo-mcp@latest"
-        ],
-        "env": {
-            "CODEVIDEO_TTS_PROVIDER": "kokoro",
-            "TTS_SERVICE_URL": "http://localhost:3000"
+    "mcpServers": {
+        "codevideo-mcp": {
+            "command": "npx",
+            "args": [
+                "-y",
+                "@fullstackcraftllc/codevideo-mcp@latest"
+            ],
+            "env": {
+                "CODEVIDEO_TTS_PROVIDER": "kokoro",
+                "TTS_SERVICE_URL": "http://localhost:3000"
+            }
         }
-    },
-    // ... other MCP servers
+    }
 }
 ```
 
 (Or the ElevenLabs and S3 variables from [Requirements](#requirements) instead of the two Kokoro ones.)
 
+## Usage with Claude Code
+
+```shell
+claude mcp add codevideo -e CODEVIDEO_TTS_PROVIDER=kokoro -e TTS_SERVICE_URL=http://localhost:3000 -- npx -y @fullstackcraftllc/codevideo-mcp@latest
+```
+
+Pass the ElevenLabs and S3 variables with `-e` instead of the two Kokoro ones if you use ElevenLabs.
+
 ## Usage with Codex
 
 Add the published MCP server to `~/.codex/config.toml`:
@@ -117,6 +125,7 @@ All four video tools take the same `options`:
 | `keyboardTypingPauseMs`, `standardPauseMs`, `longPauseMs` | pacing |
 | `voiceId`, `ttsProvider` | narration voice and provider |
 | `renderMode` | `realtime` (default) or `deterministic`; `renderSeed` and `renderWorkers` (1–32) apply to deterministic renders |
+| `isDiagnosticsVisible` | `true` / `false`: TypeScript squiggles in the editor from the start; lessons can also turn them on and off with `editor-show-diagnostics` and `editor-hide-diagnostics` |
 
 They also take `open`: whether to open the finished video in your default player. It defaults to on for single videos and off for whole courses.
 
@@ -124,7 +133,7 @@ Videos are saved to `CODEVIDEO_OUTPUT_DIR`, or your Desktop.
 
 ## Where your data lives
 
-Everything is under `~/.codevideo/`:
+Everything is under `~/.codevideo/`, or the folder `CODEVIDEO_HOME` points to:
 
 - `codevideo.db`: courses, lessons, the legacy single slot, and the render queue.
 - `jobs/<jobId>/`: each render's project, settings and CLI logs (`stdout.log`, `stderr.log`); `jobs/worker.log` is the worker's own log.
@@ -180,3 +189,16 @@ Then, use the following JSON to run the local version on your Claude Desktop:
 
 - Compile checks can't resolve third-party packages yet: a lesson that imports `react` reports "Cannot find module 'react'", so courses that depend on npm packages can't pass `codevideo_validate_course`.
 - With CLI 0.0.13, a project is passed to the CLI on its command line, so a single lesson is limited to about 120 KiB as JSON (about 30 KB on Windows). The MCP refuses bigger ones with a clear message.
+
+
+## Lesson verification
+
+`codevideo_compile_lesson` freshly replays a lesson from a cloned initial snapshot and checks its saved end-state projects. It reports `outcome: passed | failed | blocked | unsupported`; legacy `status` is `ok` only for passed. Each project reports its root, declared check (`syntax`, `typecheck`, `build`), checked/supporting/unsupported paths, compiler version, structured errors and prerequisite issues. Missing tools/dependencies and nothing-checkable lessons never pass.
+
+Dirty editor buffers and disagreement with a stored final snapshot are reported in `lessonIssues`; the server does not autosave or silently repair snapshots. Save buffers using actions, then reapply edits and recheck. Replay warnings remain warnings. Course completion requires passed verification for every mustCompile lesson and the final lesson. Intermediate mustCompile:false lessons remain available for deliberate errors or discussion.
+
+TS/JS verification uses real compiler inputs, local project configuration and available dependency declarations. No generated untyped import shims are used. The existing `diagnostics` field and hover checks remain Monaco-compatible presentation checks and do not establish a project pass. Python guarantees syntax only; Go and C# perform offline builds. Rust is explicitly unsupported. See dynamic AST's README for prerequisites and limitations; native builds are not a security sandbox.
+
+No dependency restoration from the network occurs during verification. `CODEVIDEO_HOME` optionally sets the MCP state directory (default ~/.codevideo), including for isolated tests.
+
+To test unreleased compiler changes without publishing: build dynamic AST and create a tarball with `npm pack --ignore-scripts`; install it locally with `npm install --no-save --package-lock=false <tarball>`, then run the MCP typecheck, tests and build. If the existing local diagnostics changes in codevideo-types are also unreleased, pack that package and set `CODEVIDEO_TYPES_TARBALL` to its absolute path. Set `CODEVIDEO_DYNAMIC_AST_TARBALL` to the compiler tarball path when running `npm run smoke:packed` to exercise the actual packaged compiler through MCP. Neither package version is changed by this workflow. Before shipping, the corresponding compiler release must be published and the MCP dependency/lockfile updated together.

package/dist/index.js

@@ -2,11 +2,11 @@
 
 // src/index.ts
 import dotenv from "dotenv";
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 import { fileURLToPath } from "node:url";
 
 // package.json
-var version = "1.1.0";
+var version = "1.2.0";
 
 // src/index.ts
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -89,7 +89,7 @@ var AUTHORING_RULES = `ACTION STYLE AND PACING (this is what makes lessons clear
 - Never use file-explorer-create-file, file-explorer-create-folder or file-explorer-set-file-contents: they change files with nothing on screen causing it, so things just appear. Don't use the composite-* actions or editor-highlight-code either: they aren't supported yet and do nothing. codevideo_validate_course rejects lessons that use any of these.
 - A file you just created with the mouse is ALREADY open in the editor \u2014 type into it immediately with editor-type; do NOT reopen it. A file made with touch is not open yet: open it as below. When a lesson continues from the previous one, the file you last edited is already the active editor.
 - To open a DIFFERENT existing file: mouse-move-file-explorer-file "<filename>" -> file-explorer-open-file "<filename>". IMPORTANT: file-explorer-open-file's value is the FILENAME, not "1" \u2014 using "1" opens a stray editor and your typing is lost.
-- Save with editor-save once a file's typing is done (narrating it first): compile checks and file reads see saved contents only.
+- Save with editor-save once a file's typing is done (narrating it first): verification rejects unsaved buffers and checks saved files. After editing, call codevideo_compile_lesson: only outcome passed verifies the declared check. failed means fix the lesson, blocked means prerequisites are unavailable, unsupported means no implemented check. Check each project's check kind: syntax, typecheck, or build. Monaco diagnostics reproduce presentation only; they do not prove a project builds. Verification never installs dependencies; author required manifests/configuration and use available dependency declarations or self-contained examples.
 - editor-type's value is the literal text to insert (including newlines).
 
 NARRATION:
@@ -280,7 +280,7 @@ import os from "node:os";
 import path from "node:path";
 import { createRequire } from "node:module";
 var codevideoHome = () => {
-  const dir = path.join(os.homedir(), ".codevideo");
+  const dir = process.env.CODEVIDEO_HOME || path.join(os.homedir(), ".codevideo");
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 };
@@ -1012,6 +1012,7 @@ var RenderOptionsSchema = z.object({
   isEditorTabsVisible: z.boolean().optional(),
   isMinimapVisible: z.boolean().optional(),
   isMouseVisible: z.boolean().optional().describe("Draw the mouse cursor. Mouse actions keep their timing and effects when it's hidden."),
+  isDiagnosticsVisible: z.boolean().optional().describe("Show TypeScript squiggles (red errors, yellow warnings) for the whole video. editor-show-diagnostics / editor-hide-diagnostics actions switch them for part of a lesson instead."),
   wordWrap: z.enum(["on", "off"]).optional(),
   keyboardTypingPauseMs: z.number().int().positive().optional(),
   standardPauseMs: z.number().int().positive().optional(),
@@ -1037,6 +1038,7 @@ var IDE_PROP_KEYS = [
   "isEditorTabsVisible",
   "isMinimapVisible",
   "isMouseVisible",
+  "isDiagnosticsVisible",
   "wordWrap",
   "keyboardTypingPauseMs",
   "standardPauseMs",
@@ -1545,8 +1547,8 @@ var validateActions = (actions) => {
 };
 
 // src/tools/courseTools.ts
-import fs7 from "node:fs";
-import path7 from "node:path";
+import fs8 from "node:fs";
+import path8 from "node:path";
 import { isValidAction as isValidAction2 } from "@fullstackcraftllc/codevideo-types";
 
 // src/store/courseStore.ts
@@ -1852,41 +1854,181 @@ var getLessonFile = (courseId, lessonId, filePath) => {
   const entry = fileEntriesFromSnapshot(lesson.finalSnapshot).find((f) => samePath(f.path, filePath));
   return entry ? entry.content : null;
 };
-var getLessonFiles = (courseId, lessonId) => {
-  const lesson = getLesson(courseId, lessonId);
-  return fileEntriesFromSnapshot(lesson.finalSnapshot);
-};
+
+// src/tools/verifyLesson.ts
+import { isDeepStrictEqual } from "node:util";
+import { VirtualIDE as VirtualIDE3 } from "@fullstackcraftllc/codevideo-virtual-ide";
 
 // src/tools/compileCheck.ts
+import { createRequire as createRequire3 } from "node:module";
+
+// src/tools/diagnostics.ts
 import { createRequire as createRequire2 } from "node:module";
-var cachedCompileProject = null;
-var getCompileProject = () => {
-  if (!cachedCompileProject) {
-    const require2 = createRequire2(import.meta.url);
-    cachedCompileProject = require2("@fullstackcraftllc/codevideo-dynamic-ast").compileProject;
+import fs7 from "node:fs";
+import path7 from "node:path";
+import {
+  DIAGNOSTICS_TYPESCRIPT_VERSION,
+  createDiagnosticsShims,
+  getDiagnosticsChecks,
+  getDiagnosticsCompilerOptions,
+  isDiagnosticsProgramFile,
+  normalizeDiagnosticsPath,
+  toCodeVideoDiagnostic,
+  toDiagnosticsFileName
+} from "@fullstackcraftllc/codevideo-types";
+var cachedTypeScript = null;
+var loadTypeScript = () => {
+  if (!cachedTypeScript) {
+    const ts = createRequire2(import.meta.url)("typescript-5.4.5");
+    if (ts.version !== DIAGNOSTICS_TYPESCRIPT_VERSION) {
+      throw new Error(`Diagnostics need TypeScript ${DIAGNOSTICS_TYPESCRIPT_VERSION} (the renderer's), found ${ts.version}`);
+    }
+    cachedTypeScript = ts;
+  }
+  return cachedTypeScript;
+};
+var isDiagnosticsFile = (filePath) => isDiagnosticsProgramFile(normalizeDiagnosticsPath(filePath));
+var computeDiagnostics = (files, targets) => {
+  const ts = loadTypeScript();
+  const project = files.map((file) => ({ path: normalizeDiagnosticsPath(file.path), content: file.content }));
+  const program = [...project.filter((file) => isDiagnosticsProgramFile(file.path)), createDiagnosticsShims(project)];
+  const sources = new Map(program.map((file) => [toDiagnosticsFileName(file.path), file.content]));
+  const options = getDiagnosticsCompilerOptions();
+  const libDirectory = path7.dirname(ts.getDefaultLibFilePath(options));
+  const isLib = (fileName) => fileName.startsWith(libDirectory) && fs7.existsSync(fileName);
+  const read = (fileName) => sources.get(fileName) ?? (isLib(fileName) ? fs7.readFileSync(fileName, "utf8") : void 0);
+  const host = {
+    getScriptFileNames: () => [...sources.keys()],
+    getScriptVersion: () => "1",
+    getScriptSnapshot: (fileName) => {
+      const text = read(fileName);
+      return text === void 0 ? void 0 : ts.ScriptSnapshot.fromString(text);
+    },
+    getCurrentDirectory: () => "",
+    getCompilationSettings: () => options,
+    getDefaultLibFileName: (settings) => ts.getDefaultLibFilePath(settings),
+    fileExists: (fileName) => sources.has(fileName) || isLib(fileName),
+    readFile: read
+  };
+  const service = ts.createLanguageService(host, ts.createDocumentRegistry());
+  try {
+    const contents = new Map(project.map((file) => [file.path, file.content]));
+    const wanted = [...new Set((targets ?? project.map((file) => file.path)).map(normalizeDiagnosticsPath))].sort();
+    const diagnostics = [];
+    for (const target of wanted) {
+      const checks = getDiagnosticsChecks(target), content = contents.get(target);
+      if (!checks || content === void 0) continue;
+      const fileName = toDiagnosticsFileName(target);
+      const raw = [
+        ...checks.syntactic ? service.getSyntacticDiagnostics(fileName) : [],
+        ...checks.semantic ? service.getSemanticDiagnostics(fileName) : []
+      ];
+      diagnostics.push(...raw.map((diagnostic) => toCodeVideoDiagnostic(target, content, diagnostic)));
+    }
+    return diagnostics;
+  } finally {
+    service.dispose();
   }
-  return cachedCompileProject;
 };
+
+// src/tools/compileCheck.ts
+var compiler;
 var compileFiles = async (files) => {
-  if (files.length === 0) {
-    return { status: "ok", projects: [], message: "No files to compile." };
+  let result;
+  try {
+    compiler ??= createRequire3(import.meta.url)("@fullstackcraftllc/codevideo-dynamic-ast").compileProject;
+    result = await compiler(files);
+    if (!result.outcome) throw new Error("Installed dynamic-ast lacks explicit verification outcomes; install the updated package.");
+  } catch (error) {
+    result = { outcome: "blocked", projects: [{ language: "unknown", root: ".", check: "syntax", outcome: "blocked", errors: [], issues: [{ kind: "runner", message: String(error) }], checkedPaths: [], supportingPaths: [], unsupportedPaths: [] }] };
   }
+  const response = { ...result, status: result.outcome === "passed" ? "ok" : "errors" };
+  if (files.some((f) => isDiagnosticsFile(f.path))) {
+    try {
+      response.diagnostics = computeDiagnostics(files);
+    } catch (error) {
+      response.presentationIssues = [String(error)];
+    }
+  }
+  return response;
+};
+
+// src/tools/verifyLesson.ts
+var verifyLesson = async (lesson) => {
+  const issues = [];
+  const warnings = [];
+  const ide = new VirtualIDE3();
+  let index = -1;
+  let snapshot;
   try {
-    const compileProject = getCompileProject();
-    const result = await compileProject(files);
-    const projects = result.projects.map((p) => ({
-      language: p.language,
-      errors: p.errors
-    }));
-    const hasErrors = projects.some((p) => p.errors.length > 0);
-    return { status: hasErrors ? "errors" : "ok", projects };
+    if (lesson.initialSnapshot) ide.applyCourseSnapshot(structuredClone(lesson.initialSnapshot));
+    let seen = 0;
+    for (index = 0; index < lesson.actions.length; index++) {
+      ide.applyAction(lesson.actions[index]);
+      const logs = ide.getLogs();
+      for (const log2 of logs.slice(seen)) {
+        if (log2.type === "error") issues.push({ kind: "replay", actionIndex: index, message: log2.message });
+        if (log2.type === "warning") warnings.push({ actionIndex: index, message: log2.message });
+      }
+      seen = logs.length;
+    }
+    snapshot = ide.getCourseSnapshot();
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      status: "errors",
-      projects: [{ language: "unknown", errors: [{ file: "unknown", line: 0, message: `Compile check failed to run: ${message}` }] }]
-    };
+    issues.push({ kind: "replay", actionIndex: index < 0 ? void 0 : Math.min(index, lesson.actions.length - 1), message: String(error) });
+    return { status: "errors", outcome: "failed", projects: [], fileCount: 0, lessonIssues: issues, warnings };
+  }
+  if (lesson.finalSnapshot && !isDeepStrictEqual(snapshot, lesson.finalSnapshot)) issues.push({ kind: "snapshot", message: "Stored final snapshot disagrees with initial snapshot plus actions. Reapply the lesson actions to recompute the snapshot chain." });
+  for (const editor of snapshot.editorSnapshot.editors) {
+    if (!editor.isSaved) issues.push({ kind: "unsaved", path: editor.filename, message: `Unsaved buffer ${editor.filename}: add an editor-save action before the lesson ends.` });
   }
+  const files = ide.getFullFilePathsAndContents();
+  const compiled = await compileFiles(files);
+  const outcome = issues.length ? "failed" : compiled.outcome;
+  return { ...compiled, status: outcome === "passed" ? "ok" : "errors", outcome, fileCount: files.length, lessonIssues: issues, warnings };
+};
+
+// src/validation/diagnosticHovers.ts
+import { VirtualIDE as VirtualIDE4 } from "@fullstackcraftllc/codevideo-virtual-ide";
+import {
+  diagnosticContains,
+  normalizeDiagnosticsPath as normalizeDiagnosticsPath2,
+  parseDiagnosticLocation
+} from "@fullstackcraftllc/codevideo-types";
+var filesOnScreen = (ide) => {
+  const files = new Map(ide.getFullFilePathsAndContents().map((file) => [normalizeDiagnosticsPath2(file.path), file.content]));
+  for (const editor of ide.getEditorSnapshot().editors) files.set(normalizeDiagnosticsPath2(editor.filename), editor.content);
+  return [...files].map(([path10, content]) => ({ path: path10, content }));
+};
+var checkDiagnosticHovers = (initialSnapshot, actions) => {
+  if (!actions.some((action) => action.name === "mouse-move-editor-diagnostic")) return [];
+  const ide = new VirtualIDE4();
+  ide.applyCourseSnapshot(structuredClone(initialSnapshot));
+  const problems = [];
+  actions.forEach((action, index) => {
+    if (action.name === "mouse-move-editor-diagnostic") {
+      const location = parseDiagnosticLocation(action.value);
+      const active = ide.getEditorSnapshot().editors.find((editor) => editor.isActive);
+      if (!location) {
+        problems.push({ index, value: action.value, reason: "the value isn't a 'path:line:column' location" });
+      } else if (!active || normalizeDiagnosticsPath2(active.filename) !== location.path) {
+        problems.push({ index, value: action.value, reason: `${location.path} isn't the active editor here (active: ${active?.filename ?? "none"})` });
+      } else {
+        const diagnostics = computeDiagnostics(filesOnScreen(ide), [location.path]);
+        const column = location.column;
+        const hit = column === void 0 ? diagnostics.some((d) => d.line === location.line) : diagnostics.some((d) => diagnosticContains(d, location.line, column));
+        if (!hit) {
+          const there = diagnostics.map((d) => `${d.line}:${d.column}-${d.endLine}:${d.endColumn} "${d.message.split("\n")[0]}"`);
+          problems.push({
+            index,
+            value: action.value,
+            reason: there.length ? `no squiggle at that spot; ${location.path} has ${there.join("; ")}` : `${location.path} has no squiggles at this point in the lesson`
+          });
+        }
+      }
+    }
+    ide.applyAction(action);
+  });
+  return problems;
 };
 
 // src/tools/courseTools.ts
@@ -1899,8 +2041,8 @@ var filesChangedBy = (lesson) => {
   const before = new Map(fileEntriesFromSnapshot(lesson.initialSnapshot).map((f) => [f.path, f.content]));
   const open = new Set((lesson.finalSnapshot.editorSnapshot?.editors ?? []).map((e) => e.filename));
   return fileEntriesFromSnapshot(lesson.finalSnapshot).filter((f) => before.get(f.path) !== f.content).slice(0, 10).map((f) => {
-    const path9 = f.path.replace(/^\/+/, "");
-    return { path: path9, change: before.has(f.path) ? "changed" : "created", open: open.has(path9) };
+    const path10 = f.path.replace(/^\/+/, "");
+    return { path: path10, change: before.has(f.path) ? "changed" : "created", open: open.has(path10) };
   });
 };
 var addLessonTool = (courseId, input) => {
@@ -1950,9 +2092,8 @@ var getLessonFileTool = (courseId, lessonId, filePath) => {
   return ok({ courseId, lessonId, path: filePath, found: true, content });
 };
 var compileLessonTool = async (courseId, lessonId) => {
-  const files = getLessonFiles(courseId, lessonId);
-  const result = await compileFiles(files);
-  return ok({ courseId, lessonId, fileCount: files.length, ...result });
+  const result = await verifyLesson(getLesson(courseId, lessonId));
+  return ok({ courseId, lessonId, ...result });
 };
 var validateCourse = async (courseId) => {
   const lessons = listLessons(courseId);
@@ -1971,11 +2112,13 @@ var validateCourse = async (courseId) => {
     }
     let compileStatus = "skipped";
     let compileErrors = [];
+    let verification;
     if (lesson.mustCompile) {
-      const c = await compileFiles(getLessonFiles(courseId, lesson.id));
+      const c = verification = await verifyLesson(lesson);
       compileStatus = c.status;
-      compileErrors = c.projects.filter((p) => p.errors.length > 0);
+      compileErrors = c.projects.filter((p) => p.outcome !== "passed");
     }
+    const diagnosticHoverProblems = checkDiagnosticHovers(lesson.initialSnapshot, lesson.actions);
     results.push({
       lessonId: lesson.id,
       name: lesson.name,
@@ -1988,7 +2131,9 @@ var validateCourse = async (courseId) => {
       snapshotContinuous,
       mustCompile: lesson.mustCompile,
       compileStatus,
-      compileErrors
+      compileErrors,
+      verification,
+      diagnosticHoverProblems
     });
   }
   const allActionsValid = results.every((r) => r.actionsValid);
@@ -2000,7 +2145,8 @@ var validateCourse = async (courseId) => {
   const allMustCompileClean = compileEnforced.every((r) => r.compileStatus === "ok");
   const finalLesson = results[results.length - 1];
   const finalCompilesClean = !!finalLesson && finalLesson.mustCompile && finalLesson.compileStatus === "ok";
-  const done = lessons.length > 0 && allHaveActions && allActionsValid && allAllowed && allOpenWithSpeech && allContinuous && allMustCompileClean && finalCompilesClean;
+  const allHoversLand = results.every((r) => r.diagnosticHoverProblems.length === 0);
+  const done = lessons.length > 0 && allHaveActions && allActionsValid && allAllowed && allOpenWithSpeech && allContinuous && allMustCompileClean && finalCompilesClean && allHoversLand;
   const reasons = [];
   if (lessons.length === 0) reasons.push("Course has no lessons.");
   for (const lesson of results.filter((result) => !result.hasActions)) {
@@ -2021,8 +2167,16 @@ var validateCourse = async (courseId) => {
   for (const result of results.filter((r) => r.rejectedActions.length > 0)) {
     reasons.push(`Lesson "${result.name}" (${result.lessonId}) uses actions lessons can't use; ${describeRejected(result.rejectedActions)}.`);
   }
+  for (const result of results.filter((r) => r.diagnosticHoverProblems.length > 0)) {
+    const details = result.diagnosticHoverProblems.map((p) => `action ${p.index} (${p.value}): ${p.reason}`);
+    reasons.push(`Lesson "${result.name}" (${result.lessonId}) has mouse-move-editor-diagnostic actions that miss: ${details.join("; ")}.`);
+  }
   if (!allContinuous) reasons.push("Some lessons do not follow cleanly from the previous lesson (snapshot discontinuity).");
-  if (!allMustCompileClean) reasons.push("Some lessons marked mustCompile do not compile cleanly.");
+  for (const result of results.filter((r) => r.mustCompile && r.verification?.outcome !== "passed")) {
+    const verification = result.verification;
+    const detail = [...verification.lessonIssues.map((i) => i.message), ...verification.projects.flatMap((p) => p.issues.map((i) => i.message))].join("; ");
+    reasons.push(`Lesson "${result.name}" verification ${verification.outcome}: ${detail}`);
+  }
   if (finalLesson && !finalLesson.mustCompile) reasons.push("The final lesson must be marked mustCompile (all code should work by the end).");
   else if (!finalCompilesClean) reasons.push("The final lesson does not compile cleanly.");
   return { courseId, done, lessonCount: lessons.length, lessons: results, reasons };
@@ -2050,11 +2204,11 @@ var getCourseStatusTool = (courseId) => {
 };
 var exportCourseTool = (courseId) => {
   const course = exportCourse(courseId);
-  const dir = path7.join(codevideoHome(), "exports");
-  fs7.mkdirSync(dir, { recursive: true });
-  const file = path7.join(dir, `${courseId.replace(/[^a-z0-9-_]+/gi, "_")}.json`);
+  const dir = path8.join(codevideoHome(), "exports");
+  fs8.mkdirSync(dir, { recursive: true });
+  const file = path8.join(dir, `${courseId.replace(/[^a-z0-9-_]+/gi, "_")}.json`);
   const json = JSON.stringify(course, null, 2);
-  fs7.writeFileSync(file, json);
+  fs8.writeFileSync(file, json);
   return ok({
     courseId,
     path: file,
@@ -2066,8 +2220,8 @@ var exportCourseTool = (courseId) => {
 
 // src/tools/renderTools.ts
 import os4 from "os";
-import fs8 from "fs";
-import path8 from "path";
+import fs9 from "fs";
+import path9 from "path";
 import { generateHtmlStringFromLesson } from "@fullstackcraftllc/codevideo-exporters";
 var ok2 = (data) => JSON.stringify(data, null, 2);
 var toILesson = (l) => ({
@@ -2080,10 +2234,10 @@ var toILesson = (l) => ({
 });
 var writePreviewHtml = async (courseId, l) => {
   const html = await generateHtmlStringFromLesson(toILesson(l), {});
-  const outDir = path8.join(os4.homedir(), ".codevideo", "previews", courseId);
-  fs8.mkdirSync(outDir, { recursive: true });
-  const file = path8.join(outDir, `${l.id}.html`);
-  fs8.writeFileSync(file, html, "utf8");
+  const outDir = path9.join(os4.homedir(), ".codevideo", "previews", courseId);
+  fs9.mkdirSync(outDir, { recursive: true });
+  const file = path9.join(outDir, `${l.id}.html`);
+  fs9.writeFileSync(file, html, "utf8");
   return file;
 };
 var generateLessonPreviewTool = async (courseId, lessonId) => {
@@ -3122,8 +3276,9 @@ function setupMcpServerTools(server) {
   const tool = server.tool.bind(server);
   tool(
     "codevideo_instructions_to_create_a_course",
+    "Instructions for building a multi-lesson course as one JSON object passed between tool calls (the older flow: codevideo_create_course_with_initial_metadata, then codevideo_add_lesson_to_course per lesson). For new courses prefer the server-side flow in codevideo_instructions_to_build_course_from_scratch.",
     {
-      additionalContext: z2.string()
+      additionalContext: z2.string().describe("What to build, in your own words: the lessons for a course, or the topic for a lesson.")
     },
     async ({ additionalContext }) => {
       return {
@@ -3136,8 +3291,9 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_instructions_to_create_lesson_actions",
+    "Instructions for writing the actions of a single lesson: the action reference, the authoring rules, and how to store and render the result.",
     {
-      additionalContext: z2.string()
+      additionalContext: z2.string().describe("What to build, in your own words: the lessons for a course, or the topic for a lesson.")
     },
     async ({ additionalContext }) => {
       return {
@@ -3150,8 +3306,9 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_instructions_to_create_lesson_video",
+    "Instructions for writing a single lesson and rendering it to video, either from an actions array (codevideo_make_video_from_actions) or from a full lesson object with snapshots (codevideo_make_video_from_lesson).",
     {
-      additionalContext: z2.string()
+      additionalContext: z2.string().describe("What to build, in your own words: the lessons for a course, or the topic for a lesson.")
     },
     async ({ additionalContext }) => {
       return {
@@ -3181,6 +3338,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_get_empty_lesson_snapshot",
+    "An empty course snapshot (no files, editors or terminal output) as JSON, to use as the initialSnapshot of a lesson that starts from nothing.",
     {},
     async () => {
       return {
@@ -3193,6 +3351,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_create_course_with_initial_metadata",
+    "Returns a new course object as JSON (id, name, description, primaryLanguage, no lessons) for the older flow where the course JSON is passed between tool calls. Nothing is stored; the server-side flow uses codevideo_create_course.",
     {
       id: z2.string(),
       name: z2.string(),
@@ -3210,6 +3369,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_add_actions_to_lesson",
+    "Sets a lesson object's actions, replacing any it had, and returns the updated lesson as JSON. Nothing is stored; for stored courses use codevideo_set_lesson_actions.",
     {
       lesson: LessonSchema,
       actions: z2.array(ActionSchema)
@@ -3243,6 +3403,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_add_lesson_to_course",
+    "Appends a new, empty lesson (id, name, description, an empty initial snapshot) to a course object and returns the updated course as JSON. Nothing is stored; for stored courses use codevideo_add_lesson.",
     {
       course: CourseSchema,
       id: z2.string(),
@@ -3274,8 +3435,9 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_get_example_actions_array_by_keyword",
+    "An example actions array as JSON for a keyword: javascript, js, console log or log; go, golang, golang console log or golang log; python, python console log or python log. Returns an empty string when nothing matches.",
     {
-      keyword: z2.string()
+      keyword: z2.string().describe("One of the keywords listed in this tool's description.")
     },
     async ({ keyword }) => {
       return {
@@ -3288,8 +3450,9 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_get_example_lesson_by_keyword",
+    "An example lesson as JSON (a Go CLI tool explored from an existing codebase) for the keyword go, golang, explore codebase, existing codebase or go cli tool. Returns an empty string when nothing matches.",
     {
-      keyword: z2.string()
+      keyword: z2.string().describe("One of the keywords listed in this tool's description.")
     },
     async ({ keyword }) => {
       return {
@@ -3428,6 +3591,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_is_repeatable_action",
+    "Whether an action's value is a repeat count (how many times to press the key or run the step) rather than text. Returns true or false.",
     {
       action: ActionSchema
     },
@@ -3642,13 +3806,13 @@ function setupMcpServerTools(server) {
     "codevideo_get_lesson_file",
     "Get the contents of ONE file at the END of a lesson (cheap targeted read instead of dumping the whole snapshot).",
     { courseId: z2.string(), lessonId: z2.string(), path: z2.string() },
-    async ({ courseId, lessonId, path: path9 }) => ({
-      content: [{ type: "text", text: getLessonFileTool(courseId, lessonId, path9) }]
+    async ({ courseId, lessonId, path: path10 }) => ({
+      content: [{ type: "text", text: getLessonFileTool(courseId, lessonId, path10) }]
     })
   );
   tool(
     "codevideo_compile_lesson",
-    "Compile the code at the end of a lesson and return only the structured errors. Use this to check a lesson builds before moving on.",
+    "Replay a lesson and verify its saved end-state projects offline. Returns passed, failed, blocked, or unsupported, with check kinds and actionable issues. Monaco diagnostics are presentation-only; dirty buffers prevent a pass.",
     { courseId: z2.string(), lessonId: z2.string() },
     async ({ courseId, lessonId }) => ({
       content: [{ type: "text", text: await compileLessonTool(courseId, lessonId) }]
@@ -3656,7 +3820,7 @@ function setupMcpServerTools(server) {
   );
   tool(
     "codevideo_validate_course",
-    "Validate the whole course: per-lesson action validity, snapshot continuity, and compilation (for mustCompile lessons + the final lesson). Returns done:true when the course is complete.",
+    "Validate actions, continuity, diagnostic hovers, and fresh saved-file project verification. Every mustCompile lesson and the final lesson must have outcome passed; blocked/unsupported/dirty/stale states prevent done:true.",
     { courseId: z2.string() },
     async ({ courseId }) => ({
       content: [{ type: "text", text: await validateCourseTool(courseId) }]
@@ -3758,7 +3922,7 @@ function setupMcpServerTools(server) {
   );
 }
 var invokedPath = process.argv[1];
-var isDirectExecution = invokedPath !== void 0 && fs9.realpathSync(fileURLToPath(import.meta.url)) === fs9.realpathSync(invokedPath);
+var isDirectExecution = invokedPath !== void 0 && fs10.realpathSync(fileURLToPath(import.meta.url)) === fs10.realpathSync(invokedPath);
 if (isDirectExecution && process.argv.includes("--render-worker")) {
   runWorker().then(
     () => process.exit(0),