jt14den · Sep 23, 2026
diff --git a/episodes/adding-citation-file.md b/episodes/adding-citation-file.md
@@ -81,7 +81,12 @@ If you have ever edited a repository record, filled in a Dublin Core field, or t
 
 ## How to Create a CITATION.cff File
 
-You will do this entirely in GitHub's web interface, in your fork. No terminal required. GitHub has this built in: name a new file `CITATION.cff` and it hands you a starter template to edit.
+You will do this entirely in the browser, in your fork. No terminal required. There are two good ways to write the file, and either one is fine:
+
+- **Option A: GitHub's template.** Name a new file `CITATION.cff` and GitHub offers a starter template to edit. Quickest if you are comfortable editing a few lines of YAML.
+- **Option B: the cffinit form.** Fill in a web form that checks your entries as you go, then paste the result into GitHub. The safer choice if YAML is new to you, or if the file has many authors.
+
+Both end the same way: a `CITATION.cff` in the root of your repository, committed to `main`.
 
 ::::::::::::::::::::::::::::::::::::: instructor
 
@@ -91,7 +96,7 @@ Learners may try to perfect authorship, contributor roles, or author order. For
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-### Create the file on GitHub
+### Option A: Create the file from GitHub's template
 
 In your fork of `software-demo`:
 
@@ -120,21 +125,27 @@ date-released: 2026-07-05
 url: "https://github.com/YOUR-USERNAME/your-repository-name"
 ```
 
-::::::::::::::::::::::::::::::::::::: callout
-
 ::::::::::::::::::::::::::::::::::::: instructor
 
 ### YAML recovery path
 
-If more than a few learners hit YAML indentation errors, switch the whole room to cffinit rather than debugging individual whitespace mistakes. The goal is citation metadata, not YAML mastery. cffinit validates as they type and produces a file they can paste.
+If more than a few learners hit YAML indentation errors, switch the whole room to Option B rather than debugging individual whitespace mistakes. The goal is citation metadata, not YAML mastery. You can also teach Option B from the start: it works well as the main demo.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-### Prefer a guided form? Use cffinit
+### Option B: Fill in the cffinit form
 
-[**cffinit**](https://citation-file-format.github.io/cffinit/) is a web wizard that walks you field by field and validates as you type. It is worth using when your metadata is more involved: many authors, a `preferred-citation` for an associated paper, keywords, or a license you want recorded precisely. Fill out the form, copy the generated file, and paste it into the same `CITATION.cff` you create on GitHub. More on the format: <https://citation-file-format.github.io/>.
+[**cffinit**](https://citation-file-format.github.io/cffinit/) is a free web form from the Citation File Format project. It walks you through the file one screen at a time and flags mistakes as you type, so you never touch the YAML directly.
 
-::::::::::::::::::::::::::::::::::::::::::::::::
+1. Open <https://citation-file-format.github.io/cffinit/> and click **Create**.
+2. **Start:** choose **Software**, enter the title (`Biodiversity Analysis Toolkit`), and leave the message blank to use the default.
+3. **Authors:** add each author. Add ORCIDs if you have them.
+4. **Identifiers:** skip for now. You will add a DOI in the next episode.
+5. Click **Finish** to jump to the end. The remaining screens (abstract, keywords, license, version) are optional; come back to them any time.
+6. Copy the file: click **Copy to clipboard** on the preview, or **Download**.
+7. Back on GitHub, in your fork: **Add file → Create new file**, name it exactly `CITATION.cff`, paste, and click **Commit changes…** to `main`.
+
+cffinit also pays off when a file gets complicated: many authors, a `preferred-citation` for an associated paper, keywords, or a license you want recorded precisely. More on the format: <https://citation-file-format.github.io/>.
 
 A finished file looks like this:
 
@@ -316,7 +327,7 @@ Typical missing pieces include:
 
 Steps:
 
-1. Create CITATION.cff.
+1. Create CITATION.cff, with GitHub's template (Option A) or the cffinit form (Option B).
 2. Add at least: title, author(s), and message.
 3. Commit and refresh to see GitHub’s citation panel.
 

diff --git a/episodes/making-software-citable.md b/episodes/making-software-citable.md
@@ -148,7 +148,7 @@ Use `sandbox.zenodo.org`, not production Zenodo. Real Zenodo records and DOIs ar
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
-To practice minting a DOI without polluting the permanent scholarly record, we will use **Zenodo Sandbox**. It works exactly like the real Zenodo but is for testing.
+To practice minting a DOI without polluting the permanent scholarly record, we will use **Zenodo Sandbox**. It walks you through the same steps as the real Zenodo, but it is a test site, with a few differences worth knowing before you start.
 
 ::::::::::::::::::::::::::::::::::::: caution
 
@@ -158,6 +158,34 @@ Real Zenodo records are permanent: a published DOI cannot be deleted. Use <https
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
+::::::::::::::::::::::::::::::::::::: callout
+
+### What to expect from Zenodo Sandbox
+
+The Sandbox is a practice space, not a smaller copy of Zenodo. Expect a few rough edges:
+
+- **It needs its own login.** Your zenodo.org account does not carry over. Log in to the Sandbox with GitHub.
+- **Its DOIs do not resolve.** Sandbox DOIs start with `10.5072`, a test prefix that is not registered with DataCite, so `https://doi.org/10.5072/...` leads to an error page. Link to the Sandbox record page instead (`https://sandbox.zenodo.org/records/...`).
+- **Records may not last.** Zenodo says the Sandbox "can be cleaned at any time." Treat your practice record as disposable.
+- **It can be slow, or miss a release.** Archiving usually takes a minute or two, but the Sandbox is sometimes slow or down, and the GitHub connection occasionally misses a release, on real Zenodo too.
+
+**If your release does not show up in Zenodo:**
+
+1. Wait a few minutes and refresh the Sandbox **Settings → GitHub** page.
+2. Check that the toggle for your repository is **ON**. If you turned it on *after* publishing the release, Zenodo did not see that release.
+3. Publish a new release (for example `v0.1.1`). Zenodo only archives releases published while the toggle is on.
+4. Still nothing? Follow along on the instructor's screen. The concepts matter more than having your own record today.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
+::::::::::::::::::::::::::::::::::::: instructor
+
+### Have a fallback ready
+
+Before the workshop, prepare your own fork with a release already archived in the Sandbox. If the Sandbox is slow or down, or a learner's release never arrives, demo from that prepared repo and keep moving; the metadata episode can use it too. Check <https://sandbox.zenodo.org> the morning of the workshop.
+
+::::::::::::::::::::::::::::::::::::::::::::::::
+
 ::::::::::::::::::::::::::::::::::::: challenge
 
 ### Predict: what happens when you publish?
@@ -205,23 +233,25 @@ Zenodo detects the release, downloads and archives a snapshot of the repository
 
 - Zenodo automatically detects your new release
 - Creates an archived snapshot
-- Assigns a permanent DOI
-- Wait a few minutes for processing
+- Assigns a DOI (on real Zenodo it is permanent; in the Sandbox it starts with `10.5072` and is for practice)
+- Wait a few minutes for processing. Nothing after five minutes? See "What to expect from Zenodo Sandbox" above
 
 **Step 5: Add DOI badge to your README**
 
-- Copy the DOI badge from your Zenodo record
-- Add it to the top of your README:
+- Copy the DOI badge Markdown from your Sandbox record page (the DOI badge on the right side of the record)
+- Add it to the top of your README. A Sandbox badge looks like this; note that it links to the Sandbox record, because Sandbox DOIs do not resolve on doi.org:
 ```markdown
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.123456.svg)](https://doi.org/10.5281/zenodo.123456)
+[![DOI](https://sandbox.zenodo.org/badge/DOI/10.5072/zenodo.123456.svg)](https://sandbox.zenodo.org/records/123456)
 ```
+- On real Zenodo the badge uses your `10.5281` DOI and links to `https://doi.org/10.5281/zenodo.123456`
 
 **Step 6: Update your CFF file with your DOI**
 
 - Add the DOI to your `CITATION.cff`:
 ```yaml
-doi: 10.5281/zenodo.123456
+doi: 10.5072/zenodo.123456
 ```
+- This is fine in your practice fork. For real software, the `doi` comes from a real Zenodo deposit and starts with `10.5281`
 
 **Result:** You now have LICENSE, CITATION.cff, and DOI.
 
@@ -245,7 +275,7 @@ This point is subtle and important, so slow down. Say: "GitHub is the live worki
 
 ### If Zenodo can't see your repository
 
-Zenodo only lists repositories you have admin rights on. For an organization repo, an org owner may need to approve Zenodo's access first; for this exercise, forking under your personal account avoids the problem entirely. (Keep the sandbox rule in mind too: a `10.5072/...` sandbox DOI is for practice, never for a paper or a real `CITATION.cff`.)
+Zenodo only lists repositories you have admin rights on. For an organization repo, an org owner may need to approve Zenodo's access first; for this exercise, forking under your personal account avoids the problem entirely. (Keep the sandbox rule in mind too: a `10.5072/...` sandbox DOI is for practice, never for a paper or for the `CITATION.cff` of software you are actually releasing.)
 
 ::::::::::::::::::::::::::::::::::::::::::::::::