Merge pull request #104 from braboj/docs/session-3-wrapup

Session 3 wrap-up: update docs

Author: braboj

docs/ONBOARDING.md

@@ -6,7 +6,7 @@ How to set up and start contributing to tutorial-git.
 ## 1. Prerequisites
 
 - Git 2.23+ (for `git switch` / `git restore`)
-- Node.js 18+ and npm
+- Node.js 22+ and npm
 - A text editor with Markdown support
 - draw.io desktop (for editing diagrams)
 
@@ -16,9 +16,14 @@ How to set up and start contributing to tutorial-git.
 ```bash
 git clone --recurse-submodules https://github.com/braboj/tutorial-git.git
 cd tutorial-git
-cd astro-site && npm install && cd ..
+cd astro-site && npm install
+ln -s ../../../assets src/content/assets   # image symlink (Linux/macOS)
+cd ..
 ```
 
+On Windows, the symlink is created as a directory copy automatically.
+The symlink is gitignored — each developer creates it locally.
+
 If you cloned without `--recurse-submodules`:
 
 ```bash
@@ -33,8 +38,9 @@ cd astro-site
 npm run dev
 ```
 
-Open `http://localhost:4321` — the Astro dev server should start. The site
-is not yet wired to `chapters/`, so content may be placeholder.
+Open `http://localhost:4321` — the Astro dev server should start. All 9
+chapters are wired as single-page sections. The site is deployed to
+`braboj.github.io/tutorial-git/` via GitHub Actions.
 
 
 ## 4. Key files

docs/PLAYBOOK.md

@@ -96,18 +96,30 @@ cd astro-site
 npm run dev       # http://localhost:4321
 ```
 
-### 3.2 Building for production
+### 3.2 Syncing chapters to the Astro site
+
+Chapters in `chapters/` are the canonical source. The Astro site reads
+copies from `astro-site/src/content/docs/`. After editing a chapter:
+
+1. Copy the file: `cp chapters/NN-slug.md astro-site/src/content/docs/slug.md`
+2. Fix cross-references — replace `(NN-slug.md)` with `(../slug/)`
+3. Verify the build: `npm run build`
+
+The filename in `content/docs/` drops the number prefix (e.g.
+`01-introduction.md` → `introduction.md`).
+
+### 3.3 Building for production
 
 ```bash
 cd astro-site
 npm run build     # output in dist/
 npm run preview   # preview the production build
 ```
 
-### 3.3 Deployment
+### 3.4 Deployment
 
 Push to `main` — GitHub Actions builds and deploys to GitHub Pages
-automatically.
+automatically. The CI creates the assets symlink before building.
 
 
 ## 4. Git workflow

docs/dev-journal.md

@@ -7,7 +7,7 @@ Architecture overview and chronological session log for tutorial-git.
 
 - **Content**: Markdown files in `chapters/` (SSG-agnostic)
 - **Assets**: `assets/images/` (PNGs), `assets/drawio/` (source diagrams)
-- **Site**: Astro static site in `astro-site/` (not yet wired to chapters)
+- **Site**: Astro static site in `astro-site/` (wired to chapters via content collection)
 - **Templates**: `docs/solid-ai-templates/` submodule for CLAUDE.md generation
 - **Hosting**: GitHub Pages via GitHub Actions
 
@@ -83,3 +83,35 @@ Architecture overview and chronological session log for tutorial-git.
 
 **Open issues:**
 - #72 — Deploy as GitHub Page (Astro site scaffolded, not wired to chapters)
+
+### 2026-04-20 — Astro site wiring and content polish
+
+**Tool:** Claude Code (Opus 4.6)
+
+**Key changes:**
+- Wired all 9 chapters to Astro site as single-page sections
+- Removed operations subsections (10 files) and test pages (2 files)
+- Renamed concepts to building-blocks to match canonical chapter
+- Added assets symlink in `src/content/` for image resolution
+- Switched CI pipeline from MkDocs to Astro (Node.js 22)
+- Added `base: '/tutorial-git/'` for GitHub Pages deployment
+- Disabled Shiki syntax highlighting — dark terminal code blocks
+- Added hamburger menu for mobile nav (≤768px breakpoint)
+- Numbered h2 headings across all chapters, added learning objectives
+- Collapsible ToC — h2 visible, h3+ expandable on click
+- Improved nav visibility — darker tab bar, WCAG AA contrast
+- Teal underline on h2, muted h3 color for visual hierarchy
+- Consolidated installation instructions (download → table → verify)
+- Rewrote introduction exercises as linear flow (install → clone → add → commit → push → pull)
+- Updated quiz to test core concepts (index, commit chain)
+- Replaced object model diagram — vertical commit chain layout
+- Created object types draw.io diagram with concrete example data
+- Fixed broken cross-references in all chapters (file links → site URLs)
+- Removed 9 dead tutorial sidebar links (only Azure and Python live)
+- Updated home page, README (solid-ai-templates conformant)
+- Upstreamed README spec change to solid-ai-templates (merged Overview into Title)
+- Closed issues: #72, #83, #84, #88, #89, #90, #91, #92, #93, #94, #98
+
+**Open issues:**
+- #100 — Add search functionality
+- #101 — Evaluate hamburger vs horizontal scroll for mobile nav