added beginner companion previews to every lesson

docs/companion-guide/README.md

@@ -0,0 +1,73 @@
+# Beginner Companion Guide
+
+A friendly "read-before-you-start" guide for the **AI Engineering From Scratch** course.
+
+This is **not** a replacement for the lessons. It's a 5–10 minute preview you read *before* opening a lesson, so that when you start, you already know:
+
+- **What** the topic is
+- **Why** it exists
+- **Why** you should learn it
+- **Where** it's used in the real world
+- **What** problem it solves
+
+Think of it as a friend explaining the lesson to you over coffee, before you sit down to do the real work.
+
+---
+
+## How to use this guide
+
+1. Pick the phase you're about to start.
+2. Read its short overview (importance, difficulty, study time).
+3. Skim the one-page preview for the specific lesson you're opening.
+4. Then open the actual lesson in `phases/` and build.
+
+You can read a whole phase's previews in about 10 minutes.
+
+---
+
+## How to read the ratings
+
+**Phase importance**
+
+- ⭐⭐⭐⭐⭐ — Essential. Don't skip.
+- ⭐⭐⭐⭐ — Important, but you can move faster.
+- ⭐⭐⭐ — Nice to know. Useful, not urgent.
+
+**Per-lesson: do I need to master this?**
+
+- 🟢 Basic understanding is enough — know what it is and move on.
+- 🟡 Learn it reasonably well — you'll use it regularly.
+- 🔴 Master this — it's a core skill you'll lean on constantly.
+
+---
+
+## The 20 phases
+
+| # | Phase | Lessons | Importance | Difficulty |
+|---|-------|:------:|:----------:|:----------:|
+| 00 | [Setup & Tooling](./00-setup-and-tooling/) | 12 | ⭐⭐⭐⭐⭐ | Easy |
+| 01 | [Math Foundations](./01-math-foundations/) | 22 | ⭐⭐⭐⭐ | Medium–Hard |
+| 02 | [ML Fundamentals](./02-ml-fundamentals/) | 18 | ⭐⭐⭐⭐⭐ | Medium |
+| 03 | [Deep Learning Core](./03-deep-learning-core/) | 13 | ⭐⭐⭐⭐⭐ | Medium–Hard |
+| 04 | [Computer Vision](./04-computer-vision/) | 28 | ⭐⭐⭐⭐ | Hard |
+| 05 | [NLP: Foundations to Advanced](./05-nlp-foundations-to-advanced/) | 29 | ⭐⭐⭐⭐⭐ | Medium–Hard |
+| 06 | [Speech & Audio](./06-speech-and-audio/) | 17 | ⭐⭐⭐ | Medium |
+| 07 | [Transformers Deep Dive](./07-transformers-deep-dive/) | 16 | ⭐⭐⭐⭐⭐ | Hard |
+| 08 | [Generative AI](./08-generative-ai/) | 15 | ⭐⭐⭐⭐ | Hard |
+| 09 | [Reinforcement Learning](./09-reinforcement-learning/) | 12 | ⭐⭐⭐ | Hard |
+| 10 | [LLMs From Scratch](./10-llms-from-scratch/) | 24 | ⭐⭐⭐⭐⭐ | Hard |
+| 11 | [LLM Engineering](./11-llm-engineering/) | 17 | ⭐⭐⭐⭐⭐ | Medium |
+| 12 | [Multimodal AI](./12-multimodal-ai/) | 25 | ⭐⭐⭐⭐ | Hard |
+| 13 | [Tools & Protocols](./13-tools-and-protocols/) | 23 | ⭐⭐⭐⭐ | Medium |
+| 14 | [Agent Engineering](./14-agent-engineering/) | 42 | ⭐⭐⭐⭐⭐ | Medium–Hard |
+| 15 | [Autonomous Systems](./15-autonomous-systems/) | 22 | ⭐⭐⭐⭐ | Hard |
+| 16 | [Multi-Agent & Swarms](./16-multi-agent-and-swarms/) | 25 | ⭐⭐⭐⭐ | Medium–Hard |
+| 17 | [Infrastructure & Production](./17-infrastructure-and-production/) | 28 | ⭐⭐⭐⭐⭐ | Hard |
+| 18 | [Ethics, Safety & Alignment](./18-ethics-safety-alignment/) | 30 | ⭐⭐⭐⭐ | Medium–Hard |
+| 19 | [Capstone Projects](./19-capstone-projects/) | 85 | ⭐⭐⭐⭐⭐ | Hard |
+
+> **Status:** ✅ Complete. All 20 phases (503 lessons) are written. Each phase folder has its own preview guide — start with the phase you're about to study.
+
+---
+
+*Read the preview. Then go build the real thing.*

server.py

@@ -0,0 +1,13 @@
+import os
+import http.server
+import socketserver
+
+PORT = 8799
+
+os.chdir("site")
+
+Handler = http.server.SimpleHTTPRequestHandler
+
+with socketserver.TCPServer(("", PORT), Handler) as httpd:
+    print(f"Serving at http://localhost:{PORT}")
+    httpd.serve_forever()

site/app.js

@@ -50,18 +50,33 @@
       var lessons = PHASES[i].lessons;
       totalLessons += lessons.length;
       for (var j = 0; j < lessons.length; j++) {
-        var staticDone = lessons[j].status === 'complete';
+        // Count only lessons the user has completed (ticked / passed quiz),
+        // not the author "content exists" status — so progress starts at 0
+        // and only climbs as the user marks lessons done.
         var userDone = false;
         if (hasProgress && lessons[j].url) {
           var lp = window.AIFSProgress.extractPath(lessons[j].url);
           if (lp) userDone = window.AIFSProgress.isLessonComplete(lp);
         }
-        if (staticDone || userDone) completeLessons++;
+        if (userDone) completeLessons++;
       }
     }
+    // A phase counts as complete only when the user has completed all of its
+    // lessons (again, user progress — not the author status).
     var completePhases = 0;
     for (var p = 0; p < PHASES.length; p++) {
-      if (PHASES[p].status === 'complete') completePhases++;
+      var ph = PHASES[p];
+      if (!ph.lessons.length) continue;
+      var allDone = true;
+      for (var q = 0; q < ph.lessons.length; q++) {
+        var phDone = false;
+        if (hasProgress && ph.lessons[q].url) {
+          var plp = window.AIFSProgress.extractPath(ph.lessons[q].url);
+          if (plp) phDone = window.AIFSProgress.isLessonComplete(plp);
+        }
+        if (!phDone) { allDone = false; break; }
+      }
+      if (allDone) completePhases++;
     }
     return {
       lessons: totalLessons,
@@ -113,13 +128,14 @@
       var total = p.lessons.length;
       var done = 0;
       for (var j = 0; j < p.lessons.length; j++) {
-        var staticDone = p.lessons[j].status === 'complete';
+        // User progress only — the per-phase "X / Y" count reflects lessons
+        // the user has completed, starting at 0.
         var userDone = false;
         if (hasProgress && p.lessons[j].url) {
           var lp = window.AIFSProgress.extractPath(p.lessons[j].url);
           if (lp) userDone = window.AIFSProgress.isLessonComplete(lp);
         }
-        if (staticDone || userDone) done++;
+        if (userDone) done++;
       }
       var statusClass = p.status.replace(/ /g, '-');
       var roman = toRoman(p.id);

site/build.js

@@ -268,6 +268,64 @@ function extractLessonMeta(relPath) {
   return result;
 }
 
+// ─── Beginner companion previews (docs/companion-guide/<slug>/README.md) ──
+/**
+ * The Beginner Companion Guide ships one markdown file per phase. Two layouts
+ * are supported, both ordered to match the phase's lessons one-to-one:
+ *   • Standard (phases 00–18): a `# Phase …` intro, then one `# <Lesson>`
+ *     section per lesson.
+ *   • Project (phase 19): a `# Phase …` intro and `## Track …` group headers,
+ *     with one `### NN — <Project>` entry per lesson.
+ *
+ * Returns the per-lesson sections in document order — { title, body }, where
+ * body is the markdown under the heading with its trailing `---` divider
+ * stripped. Returns [] if the phase has no companion file yet.
+ */
+function parseCompanionGuide(phaseSlug) {
+  const file = path.join(REPO_ROOT, 'docs', 'companion-guide', phaseSlug, 'README.md');
+  let lines;
+  try {
+    lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  } catch (_) {
+    return []; // No companion guide written for this phase — expected.
+  }
+
+  // Split into sections whose heading is exactly `entryLevel` hashes. A body
+  // runs until the next heading at the entry level or shallower (so `## Track`
+  // group headers don't bleed into a `###` entry, and nested `##`/`###` inside
+  // a `#` lesson stay part of its body).
+  function collect(entryLevel) {
+    const entryRe = new RegExp('^#{' + entryLevel + '} +(.+?)\\s*$');
+    const sections = [];
+    let cur = null, collecting = false;
+    for (const line of lines) {
+      const head = line.match(/^(#{1,6}) +(.+?)\s*$/);
+      if (head) {
+        if (entryRe.test(line)) {
+          if (cur) sections.push(cur);
+          cur = { title: head[2].trim(), body: [] };
+          collecting = true;
+          continue;
+        }
+        if (head[1].length <= entryLevel) collecting = false; // group/peer heading ends the body
+      }
+      if (collecting && cur) cur.body.push(line);
+    }
+    if (cur) sections.push(cur);
+    for (const s of sections) {
+      s.body = s.body.join('\n').replace(/\n*\s*-{3,}\s*$/, '').trim();
+    }
+    return sections;
+  }
+
+  // Standard layout: drop the first `#` section (the phase intro).
+  const h1Sections = collect(1);
+  if (h1Sections.length > 1) return h1Sections.slice(1);
+
+  // Project layout (phase 19): each lesson is a `### NN — …` entry.
+  return collect(3);
+}
+
 // ─── Parse glossary/terms.md ──────────────────────────────────────────
 function parseGlossary(content) {
   const terms = [];
@@ -449,6 +507,28 @@ function build() {
     }
   }
 
+  console.log('🧭 Attaching beginner companion previews from docs/companion-guide...');
+  // Attach companion previews for every phase. Set to an array of phase ids
+  // (e.g. [0]) to limit the in-lesson preview button to specific chapters.
+  const COMPANION_PHASES = null;
+  let companionAttached = 0;
+  for (const phase of phases) {
+    if (COMPANION_PHASES && !COMPANION_PHASES.includes(phase.id)) continue;
+    const withUrl = phase.lessons.find(l => l.url);
+    const slugMatch = withUrl && withUrl.url.match(/phases\/([^/]+)/);
+    if (!slugMatch) continue;
+    const lessonSections = parseCompanionGuide(slugMatch[1]);
+    if (!lessonSections.length) continue;
+    phase.lessons.forEach((lesson, idx) => {
+      const sec = lessonSections[idx];
+      if (sec && sec.body) {
+        lesson.companion = { title: sec.title, body: sec.body };
+        companionAttached++;
+      }
+    });
+  }
+  console.log(`   Companion previews attached: ${companionAttached}`);
+
   // Stats
   let totalLessons = 0;
   let completeLessons = 0;