chore: add an AGENTS file

.github/CONTRIBUTING.md

@@ -6,24 +6,32 @@ Contributions are welcome! This project is a workshop book built with [MyST](htt
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) (for building the book and slides)
+- [bun](https://bun.sh/) (for building the book and slides)
 - [prek](https://github.com/j178/prek) (for linting)
 
+Install dependencies with:
+
+```bash
+bun install
+```
+
 ## Building the book
 
 ```bash
-npx mystmd build --html
+bun run build-book
 ```
 
 The output is placed in `_build/html/`.
 
 ## Building the slides
 
 ```bash
-npx @marp-team/marp-cli@latest --input-dir slides --output _output
+bun run build-slides
 ```
 
-The output is placed in `_output/`.
+The output is placed in `_build/html/slides/`.
+
+To build both at once, run `bun run build`.
 
 ## Linting
 

.gitignore

@@ -3,3 +3,7 @@ _build
 _output
 node_modules
 .DS_Store
+
+# Symlink to AGENTS.md
+CLAUDE.md
+.claude/

AGENTS.md

@@ -0,0 +1,29 @@
+# Agent instructions
+
+## What this is
+
+SIMPLE-Py is a workshop that teaches simple compiled Python packaging (C++, Rust, publishing). It is **content, not code**: a [MyST](https://mystmd.org/) book plus [Marp](https://marp.app/) slides, deployed to GitHub Pages. There is no Python package to build or test here — edits are to Markdown.
+
+## Commands
+
+Package manager is **bun** (see `bun.lock`; CI runs `bun install --frozen-lockfile`).
+
+```bash
+bun run serve         # live-preview the book (myst start)
+bun run build         # build book + slides into _build/html/ (build-book then build-slides)
+bun run build-book    # myst build --html
+bun run build-slides  # marp slides/ -> _build/html/slides/
+bun run clean         # rm -rf _build
+prek -a --quiet       # lint/format everything (ruff-format, blacken-docs, prettier, codespell, etc.)
+```
+
+## Structure
+
+- **`content/`** — book chapters as Markdown, grouped by section directory (`basic-packaging/`, `compiled/`, `scikit-build/`, `other-tools/`, `interesting/`). Files are prefixed with an order number (`01_`, `02_`, …). Images live alongside their chapter, prefixed with the chapter stem (e.g. `04_distros-shipping.jpg`).
+- **`myst.yml`** — book config and the **table of contents**. Adding or reordering a chapter file requires editing the `toc` here; the filesystem order is not authoritative.
+- **`slides/`** — Marp decks (`marp: true` frontmatter, `theme: simplepy` → `slides/simplepy.css`). Named `<section>_<chapter>_<name>.md` where the leading digit ties the deck to its content section.
+
+## Conventions
+
+- `blacken-docs` formats Python code blocks inside Markdown, and `ruff-format` runs on code — keep embedded code snippets valid and formatted.
+- CI (`.github/workflows/cd.yml`) builds with `BASE_URL: /SIMPLE-Py` and deploys to Pages on push to `main`.

myst.yml

@@ -46,5 +46,7 @@ site:
   template: book-theme
   options:
     logo_text: SIMPLE-Py
-    # favicon: favicon.ico
+    # Vendored so the build never fetches mystmd.org's default favicon, which
+    # fails intermittently in CI (ERR_STREAM_PREMATURE_CLOSE).
+    favicon: favicon.ico
     # logo: site_logo.png

package.json

@@ -4,7 +4,7 @@
   "type": "module",
   "scripts": {
     "build-book": "myst build --html",
-    "build-slides": "mkdir -p _build/html/slides && marp --input-dir slides --html -o _build/html/slides/",
+    "build-slides": "mkdir -p _build/html/slides && marp --input-dir slides --html -o _build/html/slides/ && rsync -am --include='*/' --include='*.jpg' --include='*.jpeg' --include='*.png' --include='*.gif' --include='*.svg' --exclude='*' content/ _build/html/content/",
     "build": "bun run build-book && bun run build-slides",
     "serve": "myst start",
     "clean": "rm -rf _build"