build: add make build-serve for local preview

- Document build/preview process in README
- Document ADRs in README
- add small threaded server to scripts/serve.py

Assisted-by: claude-code:claude-opus-4-8

Author: lundybernard

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help prepare cookie external html serve clean
+.PHONY: help prepare cookie external html serve build-serve clean
 .DEFAULT_GOAL := help
 
 # Add help text after each target name starting with '\#\#'
@@ -31,6 +31,10 @@ serve: ## Serve site, typically on http://localhost:3000
 serve: prepare
 	(cd content && myst start)
 
+build-serve: ## Build full site (learn + cookie) and serve `./public` at http://localhost:3000
+build-serve: html-all
+	python3 scripts/serve.py 3000 public
+
 clean: ## Remove built files
 clean:
 	rm -rf content/_build public

README.md

@@ -1 +1,43 @@
 # learn.scientific-python.org
+
+Source for [learn.scientific-python.org](https://learn.scientific-python.org),
+built with [MyST-MD](https://mystmd.org/) (the `mystmd` CLI).
+
+## Layout
+
+- `content/` — the MyST source project (`myst.yml` lives here). This is the
+  main site.
+- `external-content/cookie/` — the [cookie](https://github.com/scientific-python/cookie)
+  submodule, a separate MyST site. Its build is overlaid at `/development/`.
+- `public/` — build output. The merged, deployable static site (main +
+  cookie). Written by `make html-all`; published by Netlify.
+
+## Prerequisites
+
+- **mystmd** — the `myst` CLI. See the
+  [MyST install guide](https://mystmd.org/guide/quickstart).
+- **Node** — the cookie overlay builds via `npx mystmd`, so a full build needs
+  Node available.
+- **git** — the cookie content is a submodule; `make prepare` initializes it.
+
+## Local development
+
+| Command            | What it does                                                            |
+| ------------------ | ----------------------------------------------------------------------- |
+| `make serve`       | Live-reload dev server for the **main site only**, at `localhost:3000`. |
+| `make html`        | Build the main site to `content/_build/html/`.                          |
+| `make html-all`    | Build main + cookie, merged into `public/`.                             |
+| `make build-serve` | Run `html-all`, then serve the full merged site at `localhost:3000`.    |
+| `make clean`       | Remove build output (`content/_build`, `public/`).                      |
+
+**Previewing `/development/` (cookie) locally:** `make serve` (and `myst start`)
+serve `content/` only — the cookie overlay is **not** visible there. To preview
+the full site, including `/development/`, use `make build-serve`. It is a static
+build (no live reload); rerun it after edits.
+
+## Decisions
+
+Architecture decisions are recorded in
+[`docs/decisions/`](docs/decisions/). See
+[`0001-myst-migration/`](docs/decisions/0001-myst-migration/) for the
+Hugo → MyST migration.

scripts/serve.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+
+# See https://github.com/Nakiami/MultithreadedSimpleHTTPServer/blob/master/MultithreadedSimpleHTTPServer.py
+
+# Python 3.x
+import sys
+import os
+
+from socketserver import ThreadingMixIn
+from http.server import SimpleHTTPRequestHandler, HTTPServer
+
+
+class ThreadingSimpleServer(ThreadingMixIn, HTTPServer):
+    pass
+
+
+if sys.argv[1:]:
+    port = int(sys.argv[1])
+else:
+    port = 8000
+
+if sys.argv[2:]:
+    os.chdir(sys.argv[2])
+
+server = ThreadingSimpleServer(("", port), SimpleHTTPRequestHandler)
+server.daemon_threads = True
+print(f"Starting server on 0.0.0.0:{port}")
+try:
+    server.serve_forever()
+except KeyboardInterrupt:
+    print("Finished")