CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Quarto static website (https://www.diiv.io) — a personal self-study site building toward embedded DSP software/firmware engineering. There is no application code: every page is a .qmd (Quarto Markdown) file rendered to HTML. Content is two courses (a theory syllabus and a lab-based DSP course) plus worked textbook exercise sets. The heavy lifting is math typesetting (KaTeX), so most “code” is LaTeX inside Markdown.

Commands

Quarto must be installed (quarto --version). All commands run from the repo root.

  • quarto preview — live-reloading local server; the primary dev loop. Renders on save.
  • quarto render — full build to _site/ (the output dir, gitignored).
  • quarto render course2/lab-3-2-mcp4725-dac-voltage.qmd — render a single page (fast iteration on one file).
  • quarto check — verify the Quarto install / environment.

There are no tests, linters, or build scripts beyond Quarto itself. Deployment is the rendered _site/ (GitHub Pages via CNAME → www.diiv.io). execute: freeze: auto means rendered output is cached; an explicit quarto render refreshes it.

Architecture & conventions

Config: _quarto.yml is the single source of truth for site title, navbar (left: Courses, Books / right: About, GitHub), theme (litera), and math engine (katex). Custom styling lives in styles.css.

Top-level pages: index.qmd (landing/bio), about.qmd (includes the attribution/copyright section the footer links to), courses/index.qmd (course directory + phase cards), books/index.qmd (book directory).

Two courses (the repo was refocused in July 2026; older 4-course layouts exist only in git history):

  • course1/ — Mathematical & Theoretical Foundations. A single syllabus page, course1/index.qmd — syllabus only, no per-week/lecture pages (deleted deliberately; do not recreate). 20 sections in 6 phases, each with anchors {#section-1}…{#section-20}, a course-catalog Theme line, and Read/Also read book-chapter assignments. Dependency-ordered: linear algebra → numerical LA → real analysis → probability → complex → functional analysis → distributions → convex → info theory → DSP → image/video → audio + learned SP.
  • course2/ — Embedded DSP (bench → real-time firmware). Fully lab-based: index.qmd syllabus plus 45 lab pages, one .qmd per lab, named lab-M-N-<slug>.qmd across modules 0–9 (bench basics → scope → logic analyzer/timing → I²C DAC/ADC → op-amps → STM32 ADC/DMA → core DSP → RTOS/robustness → edge ML → host-in-the-loop media pipelines). Course 1 is treated as a mastered prerequisite: applied, never re-taught.

Cross-links: Course 2 labs and book stubs deep-link course1/index.qmd#section-N. Before renumbering any Course 1 section, grep the whole repo for #section- references — the anchor map has been re-pointed before and stale links are easy to create.

Books: books/<book-slug>/ holds exercise sets, organized on three shelves in books/index.qmd (Mathematics & Theory; Signal Processing & EE; Image, Video & Audio Processing — 20 entries). Most are stubs (index.qmd only); finished ones have chapter subfolders. Two layout patterns for worked sets: - Axler LADR: per-subsection files — chNN/index.qmd + exercises-1a.qmd, exercises-1b.qmd, … - Ross: per-section files — chNN/index.qmd + exercises-s1.qmd, exercises-s2.qmd, … (Ross numbers exercises §section.exercise)

books/index.qmd lists every book with a **Minimum** line (bare-minimum chapters to work) and marks finished sets **✓ done** with the specific worked problems inline. A book gets a Books-page entry only if every listed chapter carries a workable problem set; reference-only books (e.g. Practical Electronics for Inventors) are cited inline in labs instead.

Content templates (match these when adding pages)

Course 2 lab (course2/lab-M-N-<slug>.qmd) — 11 sections in order: Goal / Recommended reading / Equipment & parts / Wiring & bench setup / Safety / Project & environment setup / Background / Procedure / Deliverable & expected results / Analysis & reconciliation / Going further. Template file: lab-0-1-power-supply-fluke-safety.qmd; richest exemplar: lab-3-2-mcp4725-dac-voltage.qmd. Predicted-vs-measured tables leave Measured cells as “…” for the owner to fill at the bench.

Exercise file: YAML title → a .callout-note block with anchor links ([Exercise N](#ex-N)) → per-exercise []{#ex-N} anchors, each followed by Exercise N. statement and Proof. with aligned LaTeX (\begin{aligned} with && \text{[justification]} columns). Mirror the formatting of an existing finished set (e.g. books/axler-ladr/ch01/exercises-1a.qmd).

Content authorship rules (important context, not editorial license)

Per the owner: section titles, theme lines, syllabus summaries, and the site skeleton were AI-assisted — but all proofs, exercise solutions, math substance, circuits, measurements, and firmware/analysis code are owner-only (done by hand, then converted to LaTeX/typeset). When asked to add content, default to scaffolding/typesetting/formatting help; do not invent mathematical content, worked solutions, or measurement results unless explicitly asked. Lab firmware snippets are illustrative only; setup scaffolding (CubeMX tables, wiring, venv instructions) is fair game, algorithm/analysis code is not. Never cut books or chapters that have owner-worked exercises.

Memory

Claude’s project memory (auto-loaded each session, outside the repo) holds the authoritative, frequently updated map: Course 1’s 20 sections and per-section book chapters, Course 2’s 45-lab list and template conventions, every book’s Minimum/status, and the #section-N anchor re-point history. Consult it before making structural changes, and update it when course/book structure changes — the repo’s organization has been renumbered/merged several times and that history matters.