Software Engineering Course — working agreement

This repo is a self-study course. It is read and written from two places: laptop (VS Code + Claude Code) and iPhone (claude.ai/code in Safari). Treat it as a shared workspace between those two sessions, not as an app codebase.

Every session

1. Read PROGRESS.md first. It is the source of truth for where the course stands. Do not infer position from git log or file mtimes.
2. Do the work for the current module.
3. Update PROGRESS.md before the session ends — current module, what was just finished, what is next, any open question. Be specific enough that a cold session on the other device can resume without asking.
4. Commit. One commit per meaningful chunk, message in the imperative (Add module 3 notes on dependency inversion).

Layout

Path	Holds
syllabus.md	The full course outline. The spine — edit deliberately.
modules/NN-slug.md	One file per module: material, worked examples, answers.
exercises/	Runnable code. Subfolder per exercise.
notes/	Free-form notes, questions, links. No structure imposed.
PROGRESS.md	Session handoff state.
site/	Astro + Starlight site. Derived — never author content here.

Teaching style

• Explain, then make me do it. Do not hand over finished exercise solutions before I have attempted them — put solutions in a collapsed <details> block or a separate -solution.md file.
• Prefer real, runnable code over pseudocode.
• When I get something wrong, say so plainly and show the corrected version.

Constraints

• The Markdown at the repo root is the single source of truth. site/ renders it; it never owns it. site/scripts/sync-content.mjs copies the root Markdown into site/src/content/docs/ at build time, injecting Starlight frontmatter and rewriting .md links into site routes. That generated directory is gitignored. Editing it is always a mistake — the next build overwrites it.
• Keep course content in plain Markdown with no frontmatter. The sync script derives each page’s title from its first # heading and strips that heading (Starlight renders the title itself). Adding frontmatter by hand is allowed and passes through untouched, but it clutters the file for phone reading — prefer not to.
• No build step is required to use the course. A phone session can read and edit any root file directly; the site rebuilds itself on push. Never introduce tooling that the content itself depends on.
• Keep line lengths reasonable (~90 cols) so files stay readable on a phone screen.
• Adding a file to modules/ or notes/ is enough — the sync script discovers them by glob and the sidebar picks them up. No config edit needed.

Site (only when working on site/)

Node lives at %LOCALAPPDATA%\node (portable install — the MSI is blocked by org policy on this machine, so don’t try to install Node any other way). From site/: npm run dev to preview, npm run build to check it compiles. Cloudflare Pages runs npm run build on every push to main.