Parallel builds: track callout PDFs, fix extension errors, remove copy step

- .gitignore: allow book/quarto/assets/images/icons/callouts/*.pdf
- Add missing callout PDFs (takeaways, pitfall, fallacy) so worktrees have them
- Extension: runtime repo-root check and clearer errors for parallel debug
- Extension: remove copyCalloutPdfsToWorktree (PDFs now in repo by default)
- README: document parallel build requirements; drop callout copy note

.gitignore

@@ -120,6 +120,8 @@ book/tools/scripts/testing/logs/
 *.lof
 *.lot
 *.pdf
+# Callout icon PDFs needed for PDF builds (and parallel worktree builds)
+!book/quarto/assets/images/icons/callouts/*.pdf
 
 # Database
 *.db

book/vscode-ext/README.md

@@ -49,6 +49,21 @@ This keeps daily actions focused while preserving easy access to tuning controls
 - Validate content: `./book/binder validate all`
 - Maintenance checks: `./book/binder maintain repo-health`
 
+## Parallel builds (Test All Chapters)
+
+**Build All Chapters (Parallel)** in the Debug view runs each chapter in a separate git worktree so multiple PDF builds run at once.
+
+**Requirements:**
+
+1. **Open the repo root** — Open the folder that contains `book/` (e.g. `mlsysbook-vols`), not a subfolder like `book/` or `book/quarto/`. The extension needs `book/binder` to be present to register commands and run parallel jobs.
+2. **Git in PATH** — Parallel mode uses `git worktree add --detach`; ensure `git` is available in the environment where the extension runs.
+3. **Optional settings** (VS Code/Cursor → Settings → MLSysBook):
+   - `mlsysbook.parallelDebugWorkers` — number of concurrent builds (default: 4).
+   - `mlsysbook.parallelDebugRoot` — directory for worktrees under repo root (default: `.mlsysbook/worktrees`).
+   - `mlsysbook.keepFailedWorktrees` — keep worktrees for failed chapters for inspection (default: true).
+
+If worktree creation fails, check the **MLSysBook Parallel Debug** output channel; the first failure will include a tip about repo root and git.
+
 ## Quarto Visual Customization
 
 The extension includes QMD-focused visual highlighting to improve scanability in long Quarto documents.

book/vscode-ext/src/commands/debugCommands.ts

@@ -18,11 +18,19 @@ const STATE_LAST_PARALLEL_VOLUME = 'mlsysbook.lastParallelVolume';
 /**
  * Test All Chapters — prompts for volume only, then builds every chapter
  * in parallel using PDF format and the configured worker count.
+ * Requires workspace opened at repo root (folder containing book/) and git in PATH.
  */
 async function runTestAllChapters(
   root: string,
   context: vscode.ExtensionContext,
 ): Promise<void> {
+  const repoRoot = getRepoRoot();
+  if (!repoRoot) {
+    vscode.window.showErrorMessage(
+      'MLSysBook: Parallel build requires the workspace to be the repository root (the folder that contains book/). Open that folder and try again.',
+    );
+    return;
+  }
   const defaultVolume = context.workspaceState.get<VolumeId>(STATE_LAST_PARALLEL_VOLUME);
   const picks = [
     { label: defaultVolume === 'vol1' ? 'Volume I (last used)' : 'Volume I', id: 'vol1' as VolumeId },
@@ -32,7 +40,7 @@ async function runTestAllChapters(
   if (!selection) { return; }
   const volumeId = selection.id;
 
-  const volumes = discoverChapters(root);
+  const volumes = discoverChapters(repoRoot);
   const volume = volumes.find(v => v.id === volumeId);
   if (!volume || volume.chapters.length === 0) {
     vscode.window.showWarningMessage(`No chapters found for ${volumeId}.`);
@@ -51,7 +59,7 @@ async function runTestAllChapters(
   );
 
   await runParallelChapterDebug({
-    repoRoot: root,
+    repoRoot,
     volume: volumeId,
     format: 'pdf',
     chapters: allChapters,

book/vscode-ext/src/utils/parallelDebug.ts

@@ -442,6 +442,9 @@ async function runParallelDebugBatch(options: BatchRunOptions): Promise<{ result
           elapsedMs: Date.now() - start,
         });
         channel.appendLine(`[${tag}] failed to create worktree (exit ${addCode})`);
+        if (index === 0) {
+          channel.appendLine('[session] Tip: ensure the workspace is the repo root and `git` is in PATH.');
+        }
         continue;
       }