VERSIONS.md — Pinned tool versions
Last verified: 2026-05-14
Cadence: Re-verified quarterly (see CONTRIBUTING.md for the smoke-test ritual).
This is the single source of truth for every tool the course is verified against. When a tool releases a new version, the course is not automatically updated to it; the maintainer re-verifies the lesson flows against the new version, then updates this table and notes the change in WHAT-CHANGED.md.
Required tools
| Tool | Pinned version | Purpose | Last verified |
|---|---|---|---|
| GitHub Codespaces (default image) | mcr.microsoft.com/devcontainers/universal:2 | Quick-start environment | 2026-05-08 |
| Node.js | 20.x LTS | Runtime for the thread project; M2 L3 (03-runtime-node.md) teaches node --version verification | 2026-05-14 |
| npm | 10.x (bundled with Node 20) | Package manager; M2 L4 (04-package-manager-npm.md) teaches npm install / npm run; pnpm divergence noted in CHEATSHEET sidebar | 2026-05-14 |
| git | 2.40+ | Version control | 2026-05-08 |
GitHub CLI (gh) | 2.50+ | Optional; convenient for Codespaces operations | 2026-05-08 |
AI coding agents
| Tool | Pinned version | Path | Notes | Last verified |
|---|---|---|---|---|
| Claude Code | latest stable (auto-updates) | Path 1 / Path 3 | Treat keystrokes as ephemeral per the freshness model; M3 dual-agent transcripts (modules/03-the-loop/01..04) captured against this version on the Last-verified date | 2026-05-14 |
| Gemini CLI | latest stable (auto-updates) | Path 2 | M3 dual-agent transcripts captured against this version on the Last-verified date; ignore-file syntax = .geminiignore per D-38; install command npm install -g @google/gemini-cli requires Node 20+ | 2026-05-14 |
Thread project stack (Phase 3 onward)
| Tool | Pinned version | Notes | Last verified |
|---|---|---|---|
| Next.js | 16.x (App Router) | Async cookies() / headers() / params is the breaking-change surface AI agents trained pre-2026 will get wrong | 2026-05-08 |
| TypeScript | 5.x | Used for thread project; AI agents use types as guardrails | 2026-05-08 |
@supabase/ssr | ^0.5 | Use the new sb_publishable_… / sb_secret_… key naming from day one (legacy anon/service_role removed end-2026) | 2026-05-08 |
| Supabase CLI | latest stable | Migrations live under supabase/migrations/ per Module 4 conventions | 2026-05-08 |
| Vercel CLI | latest stable | Deploy target | 2026-05-08 |
zod | ^3.x | Form validation for thread project | 2026-05-08 |
Course platform stack (site/)
The course site lives in site/ (built; deploys to Railway, where it will serve at https://shipyourfirstthing.com) and is not part of any lesson flow — these rows are for orientation only. Auth is email+password credentials (not magic-link email). See WHAT-CHANGED.md (2026-06-11 entry) for the decision summary.
| Tool | Pinned version | Notes | Last verified |
|---|---|---|---|
| Next.js (site) | 16.2.9 (App Router) | Renders the course markdown; lessons stay canonical on github.com | 2026-06-11 |
| Drizzle ORM | ^0.45 | Postgres schema + migrations (run at container boot, never during build) | 2026-06-11 |
Auth.js (next-auth) | 5.0.0-beta | Credentials provider; four core tables kept so OAuth/magic-link can be added without migration | 2026-06-11 |
pg | ^8.21 | Postgres driver | 2026-06-11 |
| Railway | n/a (managed) | Deploy target — repo-root railway.json + site/Dockerfile | 2026-06-11 |
How to update this table
- When you re-verify a tool against a new version, change its row's
Last verifiedcell to the new date. - If the tool itself changed in a way that affects lessons, also update affected lessons' front-matter
updated:field and add an entry toWHAT-CHANGED.md. - If a tool is deprecated or replaced, do NOT delete the row — strike it through and link to its replacement, so historical reading still makes sense.
See CONTRIBUTING.md for the quarterly smoke-test ritual that surfaces freshness issues.