2026-02-05 - Stabilize Modules 04-09 with shared venv and guided capstone agent tour

Timeline

• (Context) Noticed repeated learner failures caused by multiple Python installs and packages landing in the “wrong” interpreter.
• (Action) Standardized the course on a single shared .venv workflow to prevent Python version drift.
• (Action) Updated module workflows so every terminal session starts by activating the course environment before any other steps.
• (Action) Reworked command formatting for beginners by spacing command blocks and explicitly teaching that backticks are formatting only.
• (Action) Expanded terminal command teaching across Modules 04–09 with component-by-component explanations of command parts.
• (Failure) Hit a Chroma/collection runtime error in Module 04 (“object not callable”) and traced it to how generated scripts tend to wire the Chroma configuration files.
• (Action) Hardened the Module 04 generator prompt so the produced micro‑RAG script is version-tolerant and avoids common Chroma API footguns.
• (Action) Audited and fixed multiple module reset flows so essential “pre-built” files are preserved and student-generated artifacts are cleaned safely.
• (Action) Standardized container examples and sandbox tooling on the same Python line as the course runtime to reduce confusion.
• (Action) Strengthened the Module 08 → Module 09 progression so unlock reveal is gated behind required services and the intended safe execution path.
• (Action) Implemented a runtime lock for Module 09 using an unlock file so learners unlock once per machine and then proceed normally.
• (Action) Refactored Module 09 into an enforced interactive guided tour where learners direct the agent step-by-step and must complete each phase to continue.
• (Observation) Found wrapper path-resolution edge cases (tool working directory changes) and patched wrappers so relative paths behave predictably.
• (Open Thread) Service auto-start and first-run model downloads still vary by OS; the capstone needs the best possible fallback messaging when automation cannot help.

Context

• The course targets true beginners, so “it works on my machine” isn’t acceptable—environment drift must be prevented by design.
• Module 04 is the first dependency-heavy step (vector DB + embeddings), which makes interpreter mismatches show up as confusing runtime failures.
• Modules 06–08 introduce Docker and safe execution, so consistency between local Python and container references matters for learner trust.
• Module 09 is a capstone and should feel like a guided “whole-course replay” using prebuilt tools, not another code-generation exercise.

Actions

• Standardized the course on a single shared .venv workflow to prevent Python version drift.
• Added a “find and activate the course environment” terminal snippet to the start of each module’s workflow so learners don’t need to reason about paths.
• Reworked command presentation to reduce beginner copy/paste mistakes (spacing and explicit formatting guidance).
• Upgraded command documentation to explain what each command component means, especially around Docker build/run and Python invocation patterns.
• Updated the Module 04 prompt so generated micro‑RAG scripts handle Chroma APIs defensively and fail with beginner-friendly messages.
• Fixed reset scripts across Modules 05–08 to preserve essential starter assets while moving student output to a safe holding area.
• Updated the sandbox pilot flow so unlock reveal and “safety narrative” only occur when the sandbox actually ran and required local services are available.
• Implemented a Module 09 runtime lock using an unlock file to persist unlock status without repeatedly prompting.
• Rebuilt Module 09 into an enforced interactive tour inside the agent shell: each step shows exact commands, requires execution, and advances only on continue.
• Added a dedicated demo workspace for Module 09 so each tool has realistic inputs and visible outputs, with reset restoring the demo state from a clean snapshot.

Observations

• A shared .venv plus “activate first” is the lowest-friction way to keep beginner commands stable while eliminating multi-Python ambiguity.
• Tool wrappers must resolve paths predictably because changing working directories is a common source of “file not found” confusion in beginner workflows.
• Unlock gating is most reliable when tied to verifiable runtime conditions (service availability + sandbox success), not just “the script was called”.
• A guided tour that forces hands-on execution prevents silent skipping and turns the capstone into a repeatable, testable learning experience.

Open Threads

• Validate Ollama + Docker auto-start behavior across clean installs and document the exact “what to do next” fallback for each OS when auto-start fails.
• Decide on an offline-safe alternative for any step that depends on external network access, so the capstone can run in restricted environments.
• Decide whether any tour steps should require a file-writing (“do it”) action versus allowing safe dry-runs for maximum beginner safety.

Boundary Reminder: Seeds. No maintenance. No roadmap.