Rule: never commit build artifacts

.gitignore

@@ -1,6 +1,13 @@
+# Build artifacts are NEVER committed. CI builds the site and deploys it
+# to GitHub Pages (.github/workflows/pages.yml); see CLAUDE.md.
+
 # nix build output links
 result
 result-*
 
 # `mkdocs build` output, if you ever run mkdocs outside Nix
 documentation/site/
+
+# CI's copy of the built site for the Pages upload
+_site/
+site/

CLAUDE.md

@@ -0,0 +1,26 @@
+# CLAUDE.md
+
+MkDocs site (`documentation/`) + reveal.js deck (`slides/`), built by a
+Nix flake with zero npm. This repo is also a template
+(`nix flake init -t github:external-systems/presenting`) and an
+exportable flake-parts module (`flakeModules.default` / `.slides`,
+`lib.mkSlides`) that other flakes consume.
+
+## Rule: never commit build artifacts
+
+The website and deck are built in CI and published to GitHub Pages only.
+Never commit build output: no `result` / `result-*` links, no `_site/`,
+`site/` or `documentation/site/` (all gitignored), no built deck copied
+into the tree, no `gh-pages` branch pushes. To publish, merge to `main`;
+`.github/workflows/pages.yml` runs `nix flake check`, builds
+`.#documentation` (deck at `/slides/`) and deploys it.
+
+## Build and check
+
+```bash
+nix flake check                 # both builds + alejandra/statix/deadnix
+nix run .#watch-documentation   # live docs → http://127.0.0.1:8000
+nix run .#serve-slides          # live deck → http://127.0.0.1:8000
+```
+
+Nix only sees files git tracks: `git add` new files before building.

README.md

@@ -25,6 +25,10 @@ nix flake check                 # build both + lint the Nix code
 
 Remember to `git add` new files: Nix only sees files git tracks.
 
+Never commit build output (`result`, `_site/`, `site/`): CI builds the
+docs site, deck included, and deploys it to GitHub Pages
+(`.github/workflows/pages.yml`).
+
 The docs site this repo builds is also its tutorial: start with
 `documentation/docs/getting-started.md`, or run the preview and read it in
 the browser.