Update README.md: Enhance project description and local development instructions

Author: aaronjnewman

README.md

@@ -1,4 +1,44 @@
-# NESC_3505_textbook
-Repository for textbook for NESC 3505, Neural Data Science, at Dalhousie University
+# NESC 3505 Textbook – Neural Data Science
+
+Live site: https://neuraldatascience.io/
+
+This repository contains the source for the Neural Data Science textbook. The site is built with Jupyter Book (via MyST) and deployed automatically to GitHub Pages.
+
+## How publishing works
+
+- Pushing to the `master` branch triggers a GitHub Actions workflow that:
+  - Installs the MyST CLI and Python dependencies
+  - Builds the HTML site
+  - Deploys it to GitHub Pages
+
+You don’t need to publish locally or commit build artifacts. The CI runner builds from source and uploads the site directly.
+
+## Local development
+
+Option A: Quick static build
+
+1. Build the site
+	- `myst build --html`
+2. Open the result
+	- `_build/html/index.html`
+
+Option B: Dev server (live preview)
+
+1. If you hit npm EACCES errors on macOS, fix npm cache permissions:
+	- `sudo chown -R "$USER:$(id -gn)" ~/.npm`
+	- `npm cache verify`
+2. Start the dev server
+	- `jupyter book start`
+
+## Project configuration
+
+- Site structure and config are defined in `myst.yml`
+- Additional legacy settings may still exist in `_config.yml`; these are ignored by MyST once `myst.yml` is present
+- The GitHub Actions workflow lives at `.github/workflows/deploy.yml`
+
+## Troubleshooting
+
+- If the Actions run fails at “Upload artifact”, check that the build step created `_build/html`.
+- If the MyST CLI isn’t found locally, install it globally with `npm install -g mystmd` (Node.js ≥ 18 required).
+- To preview just a single change locally, re-run `myst build --html` and refresh your browser on `_build/html/index.html`.
 
-Formatted version here: [https://neuraldatascience.io/](https://neuraldatascience.io/)