From 8a24d011bf88b3c185c002e05a0d5ee13e2c34cc Mon Sep 17 00:00:00 2001
From: Josh de Leeuw <josh.deleeuw@gmail.com>
Date: Sat, 25 Jul 2026 11:08:20 -0400
Subject: [PATCH 1/2] docs(website,frontend): rewrite docs and wizard copy for
 researchers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rewrite the six documentation pages and the wizard's interface text for
readers who run jsPsych experiments but are not developers.

The `data/raw/` rule and the join-key concept were each restated in
several places, every time in different words and heavy with terms like
"byte-for-byte, same-named copy" and "re-serialised". Each now has one
plain-English explanation, reused where it is needed and linked to from
the rest. Wizard labels match what the docs call them, field hints drop
SPDX/canonical-URL jargon, `@type` becomes "Author type" and
"Privacy policy" becomes "Sharing restrictions" (both still naming the
underlying JSON key), and error messages say what to do next instead of
dumping exception text into the file list. The processing summary now
reports outcomes rather than counting skipped and failed files as
processed, and destructive confirmations state that files on disk are
untouched.

Two factual fixes fell out of the pass:

Validation now covers the dataset the user actually downloads. The zip
has always shipped placeholder README.md and CHANGES.md, but the
validator never saw them, so every run raised MISSING_README_DOC and
MISSING_CHANGES_DOC against documents the download does contain — and
the Review step carried a note explaining the false alarm away. Both
Psych-DS rules are presence-only (stem plus extension at the dataset
root), so handing the validator the same bytes the zip carries is an
honest check rather than a suppression, verified against
psychds-validator directly. Their content now lives once in
datasetLayout.ts, shared with the zip builder so the two cannot drift.
The project name is passed only when a zip is on offer: saving the bare
dataset_description.json produces no such files, and the warnings are
then real advice about the user's own folder.

Review also pointed at `npx @jspsych/cli validate` — a package that does
not exist on npm, with a subcommand the metadata CLI never had. Since
validation now covers the whole downloaded project, the re-validation
block was removed rather than corrected, along with its dead styles.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../docs-clarity-and-validated-readme.md      |  9 ++
 docs/dev/frontend-architecture.md             |  2 +-
 packages/frontend/README.md                   |  2 +-
 .../frontend/src/components/PreviewDrawer.tsx |  2 +-
 packages/frontend/src/components/Sidebar.tsx  |  3 +-
 packages/frontend/src/datasetLayout.ts        | 25 +++++
 packages/frontend/src/pages/Authors.tsx       | 15 +--
 packages/frontend/src/pages/DataUpload.tsx    | 96 +++++++++++--------
 packages/frontend/src/pages/Landing.tsx       |  4 +-
 packages/frontend/src/pages/ProjectInfo.tsx   | 42 ++++----
 packages/frontend/src/pages/Review.module.css | 33 -------
 packages/frontend/src/pages/Review.tsx        | 47 ++++-----
 packages/frontend/src/pages/Variables.tsx     |  5 +-
 packages/frontend/src/staging/datasetZip.ts   | 13 +--
 .../src/validation/validatePsychDS.ts         | 31 ++++--
 .../tests/AppShellIntegration.test.tsx        |  6 +-
 packages/frontend/tests/Authors.test.tsx      |  6 +-
 packages/frontend/tests/DataUpload.test.tsx   | 48 +++++-----
 .../frontend/tests/PreviewDrawer.test.tsx     |  2 +-
 packages/frontend/tests/ProjectInfo.test.tsx  | 20 ++--
 packages/frontend/tests/Review.test.tsx       | 35 ++-----
 packages/frontend/tests/Variables.test.tsx    |  4 +-
 .../frontend/tests/validatePsychDS.test.ts    | 22 +++++
 website/docs/guides/customizing-output.md     | 40 ++++----
 website/docs/guides/troubleshooting.md        | 32 ++++---
 website/docs/guides/using-the-cli.mdx         |  8 +-
 website/docs/guides/using-the-wizard.mdx      | 41 ++++----
 website/docs/introduction.md                  | 16 ++--
 website/docs/reference/cli-reference.md       | 64 ++++++++-----
 29 files changed, 363 insertions(+), 310 deletions(-)
 create mode 100644 .changeset/docs-clarity-and-validated-readme.md

diff --git a/.changeset/docs-clarity-and-validated-readme.md b/.changeset/docs-clarity-and-validated-readme.md
new file mode 100644
index 0000000..f88baa2
--- /dev/null
+++ b/.changeset/docs-clarity-and-validated-readme.md
@@ -0,0 +1,9 @@
+---
+"frontend": patch
+---
+
+In-browser validation now checks the dataset the user actually downloads. The zip has always shipped placeholder `README.md` and `CHANGES.md`, but the validator never saw them, so every run reported `MISSING_README_DOC` / `MISSING_CHANGES_DOC` for documents the download does contain — and the Review step carried a note explaining the false alarm away. The validator is now handed the same two files (both Psych-DS rules are presence-only, so this is an honest check, not a suppression), the warnings no longer appear, and the note is gone. Their content lives once in `datasetLayout.ts`, shared with the zip builder so the two can't drift. Saving only `dataset_description.json` produces no such files, so those warnings correctly still appear there.
+
+Review also no longer points at `npx @jspsych/cli validate` — a package that does not exist on npm, with a subcommand the metadata CLI never had. Since validation now covers the whole downloaded project, the re-validation block was removed rather than corrected.
+
+Wizard copy was rewritten throughout for researchers rather than developers: plainer field hints (`URL or SPDX identifier` → `A standard license name like CC-BY-4.0, or a link to the license text`), `@type` relabelled **Author type** and `Privacy policy` **Sharing restrictions** (both still naming the underlying JSON key), errors that say what to do next, no raw exception text in the file list, and a processing summary that reports outcomes (`Finished. 3 files read, 1 skipped.`) instead of counting skipped and failed files as processed. Destructive confirmations now state that files on disk are untouched.
diff --git a/docs/dev/frontend-architecture.md b/docs/dev/frontend-architecture.md
index b0dc0d5..06f63c9 100644
--- a/docs/dev/frontend-architecture.md
+++ b/docs/dev/frontend-architecture.md
@@ -148,7 +148,7 @@ The result is a `convertedFiles` map (dataset-relative path → contents) carrie
 
 **Network is required** — the validator fetches the Psych-DS schema and schema.org context at runtime. If it can't run, `validatePsychDS` throws `ValidationUnavailableError` with a connectivity-first message (underlying error appended), which Review surfaces as an `unavailable` banner rather than a false "invalid" result.
 
-**Zip-resolved warnings:** the in-browser validator only sees the metadata + data files, so it reports `MISSING_README_DOC` / `MISSING_CHANGES_DOC`. The downloaded zip ships `README.md` and `CHANGES.md`, so Review (`ZIP_RESOLVED_WARNINGS`) shows a reassurance note explaining these clear once the downloaded dataset is validated. A `<details>` block also documents the CLI equivalent (`npx @jspsych/cli validate`).
+**Validate what gets downloaded:** the zip ships placeholder `README.md` / `CHANGES.md`, so the validator is handed the same two files and `MISSING_README_DOC` / `MISSING_CHANGES_DOC` never fire against a project that will contain them. Both Psych-DS rules are presence-only (stem + extension at the dataset root), so this is an honest check rather than a suppression. Content lives in `datasetLayout.ts` (`datasetDocs()`), shared by `datasetZip.ts` and `validatePsychDS.ts` so the two cannot drift. Review passes the project name only when `hasDataFiles` — with no data there is no zip, so those warnings are real advice about the user's own folder and must still surface.
 
 > The core `@jspsych/metadata` library does **not** validate — validation is a consuming concern owned by the frontend (here) and the CLI (`packages/cli/src/validatefunctions.ts`). Unit tests for these helpers are tracked in issue #94.
 
diff --git a/packages/frontend/README.md b/packages/frontend/README.md
index 471fa49..6f36f66 100644
--- a/packages/frontend/README.md
+++ b/packages/frontend/README.md
@@ -99,7 +99,7 @@ Inspect the generated `dataset_description.json` and download your project:
   ```
 - If no data files were uploaded, a **Save `dataset_description.json`** button is shown instead.
 - **Validate dataset** runs the Psych-DS validator entirely in your browser and lists any errors and warnings inline, each with the underlying rule key and the specific files/columns at fault. An internet connection is required — the validator fetches the Psych-DS schema and schema.org context at runtime.
-  - Because in-browser validation only sees your metadata and data files, it may report missing `README` / `CHANGES` warnings. These are expected: the downloaded zip already includes `README.md` and `CHANGES.md`, so they clear when you validate the downloaded dataset (e.g. with `npx @jspsych/cli validate`).
+  - The check covers exactly what the zip will contain, including its placeholder `README.md` and `CHANGES.md`, so there is no need to re-validate after downloading. Saving only `dataset_description.json` produces no such files, and missing `README` / `CHANGES` warnings then correctly appear.
 
 The **{} Preview** pill button (visible on all steps except Review) opens a live JSON snapshot in a slide-in drawer so you can check the output at any point without leaving the current step.
 
diff --git a/packages/frontend/src/components/PreviewDrawer.tsx b/packages/frontend/src/components/PreviewDrawer.tsx
index ebeba00..79784f9 100644
--- a/packages/frontend/src/components/PreviewDrawer.tsx
+++ b/packages/frontend/src/components/PreviewDrawer.tsx
@@ -37,7 +37,7 @@ const PreviewDrawer: React.FC<PreviewDrawerProps> = ({ jsPsychMetadata, onClose
       onClick={handleClick}
     >
       <div className={styles.drawerHeader}>
-        <span className={styles.drawerTitle}>JSON Preview</span>
+        <span className={styles.drawerTitle}>JSON preview</span>
         <button className={styles.closeBtn} onClick={onClose} aria-label="Close preview">×</button>
       </div>
       <div className={styles.drawerBody}>
diff --git a/packages/frontend/src/components/Sidebar.tsx b/packages/frontend/src/components/Sidebar.tsx
index 5aad092..b77ddbb 100644
--- a/packages/frontend/src/components/Sidebar.tsx
+++ b/packages/frontend/src/components/Sidebar.tsx
@@ -110,7 +110,8 @@ const Sidebar: React.FC<SidebarProps> = ({
         >
           <h3 id="startover-title" className={styles.dialogTitle}>Start over?</h3>
           <p id="startover-desc" className={styles.dialogText}>
-            All progress will be lost and you'll return to the welcome screen.
+            This clears the data you uploaded and everything you've entered, and takes you back to
+            the start screen. Your own files on disk are not touched.
           </p>
           <div className={styles.dialogButtons}>
             <button className={styles.confirmYes} onClick={onStartOver}>
diff --git a/packages/frontend/src/datasetLayout.ts b/packages/frontend/src/datasetLayout.ts
index e9ca0c2..0bbe92a 100644
--- a/packages/frontend/src/datasetLayout.ts
+++ b/packages/frontend/src/datasetLayout.ts
@@ -7,3 +7,28 @@
 
 /** Canonical Psych-DS metadata filename. */
 export const DATASET_DESCRIPTION_FILENAME = 'dataset_description.json';
+
+const README_FILENAME = 'README.md';
+const CHANGES_FILENAME = 'CHANGES.md';
+
+const readmeContents = (projectName: string): string =>
+  `# ${projectName}\nHuman-readable description of the project and dataset.`;
+
+const CHANGES_CONTENTS =
+  'For version tracking — if the dataset is updated after being uploaded/shared, changes (with human-readable descriptions) may be recorded here.';
+
+/**
+ * The placeholder docs Psych-DS recommends at the dataset root. The zip writes these into every
+ * download, and the in-browser validator is handed the same two files — otherwise it reports
+ * MISSING_README_DOC / MISSING_CHANGES_DOC against a project that will in fact contain them, and
+ * the user is left reading a warning about a problem that does not exist.
+ *
+ * Both Psych-DS rules are presence-only (stem + extension at the dataset root, no content
+ * requirements), so supplying the same bytes the download carries is an honest check, not a
+ * suppression. Callers must only include these when a zip is actually being produced: with no
+ * data files the user saves the bare metadata JSON, and the warnings are then real.
+ */
+export const datasetDocs = (projectName: string): { path: string; contents: string }[] => [
+  { path: README_FILENAME, contents: readmeContents(projectName) },
+  { path: CHANGES_FILENAME, contents: CHANGES_CONTENTS },
+];
diff --git a/packages/frontend/src/pages/Authors.tsx b/packages/frontend/src/pages/Authors.tsx
index 19cd2bb..16eb844 100644
--- a/packages/frontend/src/pages/Authors.tsx
+++ b/packages/frontend/src/pages/Authors.tsx
@@ -178,8 +178,8 @@ const Authors: React.FC<AuthorsProps> = ({ jsPsychMetadata, onComplete }) => {
 
     if (invalidOrcids.length > 0) {
       setBulkWarning(
-        `ORCID not saved for: ${invalidOrcids.join(', ')}. ` +
-        `ORCIDs must be in the format 0000-0001-2345-6789. Add them manually using the author cards above.`
+        `These authors were added, but their ORCID was not: ${invalidOrcids.join(', ')}. ` +
+        `An ORCID has to look like 0000-0001-2345-6789. Add theirs on the cards above.`
       );
     } else {
       setBulkWarning(null);
@@ -191,7 +191,8 @@ const Authors: React.FC<AuthorsProps> = ({ jsPsychMetadata, onComplete }) => {
       <h2 className="srOnly">Authors</h2>
       <div className={styles.page}>
       <p className={styles.subtext}>
-        Authors are optional. You can skip this step or add them later by re-opening existing metadata.
+        Authors are optional — skip this step if you like. To add them later, open your saved{' '}
+        <code>dataset_description.json</code> back up in the wizard.
       </p>
 
       <div className={styles.cardList}>
@@ -255,7 +256,7 @@ const Authors: React.FC<AuthorsProps> = ({ jsPsychMetadata, onComplete }) => {
 
                   <p className={styles.groupLabel} style={{ marginTop: '0.75rem' }}>Rarely needed</p>
                   <p className={styles.groupNote}>
-                    For schema.org compatibility — most researchers can skip these.
+                    Extra Schema.org detail. Most people can leave these blank.
                   </p>
 
                   <div className={styles.fieldRow}>
@@ -284,9 +285,9 @@ const Authors: React.FC<AuthorsProps> = ({ jsPsychMetadata, onComplete }) => {
                   </div>
 
                   <div className={styles.field}>
-                    <label className={styles.label} htmlFor={`author-type-${row.id}`}>@type</label>
+                    <label className={styles.label} htmlFor={`author-type-${row.id}`}>Author type</label>
                     <p className={styles.fieldHint}>
-                      Usually "Person" or "Organization". Leave blank if unsure.
+                      Person or Organization. Leave blank if you aren't sure — saved as <code>@type</code>.
                     </p>
                     <input
                       id={`author-type-${row.id}`}
@@ -330,7 +331,7 @@ const Authors: React.FC<AuthorsProps> = ({ jsPsychMetadata, onComplete }) => {
       ) : (
         <div className={styles.bulkPanel}>
           <p className={styles.bulkInstructions}>
-            One author per line. To include an ORCID, separate it from the name with a comma:
+            One author per line. To include an ORCID, put it after the name, separated by a comma:
           </p>
           <pre className={styles.bulkExample}>{'Jane Smith\nJohn Doe, 0000-0001-2345-6789\nAlice Lee, 0000-0002-3456-7890'}</pre>
           <textarea
diff --git a/packages/frontend/src/pages/DataUpload.tsx b/packages/frontend/src/pages/DataUpload.tsx
index 6d9f975..bf6530c 100644
--- a/packages/frontend/src/pages/DataUpload.tsx
+++ b/packages/frontend/src/pages/DataUpload.tsx
@@ -89,6 +89,12 @@ const dataFileType = (name: string): string => {
   return ext === 'jsonl' ? 'json' : ext;
 };
 
+/**
+ * The readable part of a thrown value, for the per-file status list. `String(err)` on an Error
+ * yields "Error: …", and that prefix is noise to someone scanning which of their files failed.
+ */
+const errorDetail = (e: unknown): string => (e instanceof Error ? e.message : String(e));
+
 /** Filename without its extension (e.g. "sub01.json" → "sub01"). */
 const fileStem = (name: string): string => name.replace(/\.[^./]+$/, '');
 
@@ -123,8 +129,8 @@ const disambiguateFlatFilename = (name: string, used: Set<string>): string => {
 const ReplaceConfirm: React.FC<{ onConfirm: () => void; onCancel: () => void }> = ({ onConfirm, onCancel }) => (
   <div className={styles.replaceConfirm} role="alertdialog" aria-labelledby="replace-confirm-title">
     <p id="replace-confirm-title" className={styles.replaceConfirmMsg}>
-      Replace all uploaded data? This discards the data you already staged and the variables generated
-      from it, then lets you pick a new folder or zip.
+      Replace all uploaded data? This throws away the files you've uploaded and every variable found
+      in them, then lets you pick a new folder or .zip. Your own files on disk are not touched.
     </p>
     <div className={styles.replaceConfirmBtns}>
       <button className={styles.replaceConfirmYes} onClick={onConfirm}>Yes, replace</button>
@@ -273,7 +279,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
         extracted.push(file);
       }
       if (extracted.length === 0) {
-        setPickError('No readable files found in the zip archive.');
+        setPickError("That .zip doesn't contain any files we can read. Check that your data files are inside it, then try again.");
         return;
       }
       setBatch(extracted);
@@ -281,7 +287,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
       setSourceName(zipFile.name.replace(/\.zip$/i, ''));
       setPhase('ready');
     } catch {
-      setPickError('Could not read the zip file — make sure it is a valid .zip archive.');
+      setPickError("We couldn't open that file. Check that it is a valid .zip archive, then try again.");
     }
   };
 
@@ -385,13 +391,13 @@ const DataUpload: React.FC<DataUploadProps> = ({
 
       const filePath = file.webkitRelativePath || file.name;
       if (filePath === 'dataset_description.json' || filePath.endsWith('/dataset_description.json')) {
-        update(i, { status: 'skipped', detail: 'existing metadata file' });
+        update(i, { status: 'skipped', detail: 'this is a metadata file, not data' });
         continue;
       }
 
       const type = dataFileType(file.name);
       if (type !== 'json' && type !== 'csv') {
-        update(i, { status: 'skipped', detail: 'unsupported file type' });
+        update(i, { status: 'skipped', detail: 'not a .csv, .json, or .jsonl file' });
         continue;
       }
 
@@ -401,7 +407,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
       try {
         content = await readFileAsText(file);
       } catch (e) {
-        update(i, { status: 'error', detail: String(e) });
+        update(i, { status: 'error', detail: errorDetail(e) });
         continue;
       }
 
@@ -423,7 +429,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
           const stats: { synthesizedSourceRecordId?: boolean } = {};
           const json = parseJsonData(content, { tagSourceRecordId: true }, stats);
           if (!Array.isArray(json)) {
-            update(i, { status: 'skipped', detail: 'not a jsPsych trial array' });
+            update(i, { status: 'skipped', detail: "doesn't look like a jsPsych trial list" });
             continue;
           }
           mainRows = json;
@@ -485,7 +491,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
 
         update(i, { status: 'success' });
       } catch (e) {
-        update(i, { status: 'error', detail: String(e) });
+        update(i, { status: 'error', detail: errorDetail(e) });
       }
     }
 
@@ -532,7 +538,10 @@ const DataUpload: React.FC<DataUploadProps> = ({
         await runGenerate(['trial_index'], true, fetched);
       } catch (e) {
         if (cancelled) return;
-        setPickError(`Could not load the ${sample.label} dataset. ${String(e)}`);
+        setPickError(
+          `We couldn't load the ${sample.label} dataset. Check your internet connection and ` +
+          `reload the page, or upload your own data instead. (${errorDetail(e)})`,
+        );
         setPhase('idle');
       }
     })();
@@ -571,21 +580,22 @@ const DataUpload: React.FC<DataUploadProps> = ({
           <div>
             <strong>Variables loaded from existing metadata</strong>
             <p className={styles.hasDataSub}>
-              All variable descriptions, types, and levels were loaded from your{' '}
-              <code>dataset_description.json</code>. No data upload is needed.
+              Your <code>dataset_description.json</code> already describes every variable, so you
+              can go straight on.
             </p>
           </div>
         </div>
         <p className={styles.fromExistingOptional}>
-          Optionally, upload your data folder to add new variables or refresh levels and ranges.
+          Upload your data folder only if you want to pick up new variables, or refresh the recorded
+          value ranges and levels after collecting more data.
         </p>
         <div className={styles.pickerRow}>
           <button className={styles.browseBtn} onClick={() => requestPick('folder', 'replace')}>
-            Upload data folder (optional)
+            Choose folder
           </button>
           <span className={styles.pickerOr}>or</span>
           <button className={styles.browseBtn} onClick={() => requestPick('zip', 'replace')}>
-            Upload .zip (optional)
+            Upload .zip
           </button>
         </div>
         <input ref={inputRef} type="file" multiple style={{ display: 'none' }} onChange={handleFolderChange} {...{ webkitdirectory: '' }} />
@@ -613,7 +623,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
           <div>
             <strong>Data already processed</strong>
             <p className={styles.hasDataSub}>
-              {varCount} variable{varCount !== 1 ? 's' : ''} generated.
+              {varCount} variable{varCount !== 1 ? 's' : ''} found in your data.
             </p>
           </div>
         </div>
@@ -636,7 +646,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
           </button>
           {joinKeyCandidates.length > 0 && files.length > 0 && (
             <button className={styles.reConfigureBtn} onClick={() => enterReConfigureJoinKeys('hasData')}>
-              Re-configure join keys
+              Change join keys
             </button>
           )}
         </div>
@@ -673,7 +683,8 @@ const DataUpload: React.FC<DataUploadProps> = ({
       <h2 className="srOnly">Data</h2>
       <div className={styles.page}>
       <p className={styles.description}>
-        Select your data folder or upload a .zip archive. CSV and JSON files will be processed; other file types are skipped.
+        Choose the folder holding your data files, or upload a .zip. CSV, JSON, and JSON-Lines files are
+        read; anything else is skipped. Your original files are never modified.
       </p>
 
       {/* Pickers */}
@@ -740,12 +751,12 @@ const DataUpload: React.FC<DataUploadProps> = ({
           <div className={styles.joinKeyWarning}>
             <span className={styles.warnIcon}>⚠</span>
             <div>
-              <strong>Rows need a unique identifier</strong>
+              <strong>This file needs a column that tells its rows apart</strong>
               <p className={styles.joinKeyFile}>{joinKeyProblemFile}</p>
               <p className={styles.joinKeyExplainer}>
-                <code>trial_index</code> resets to 0 for each participant in merged files, so it
-                can't tell rows apart on its own. Pick an additional column below to form a{' '}
-                <strong>join key</strong> — a unique row identifier.
+                <code>trial_index</code> isn't unique here — usually because several participants
+                were merged into one file, and it starts over at 0 for each of them. Tick another
+                column below so that together they identify every row.
               </p>
             </div>
           </div>
@@ -760,18 +771,18 @@ const DataUpload: React.FC<DataUploadProps> = ({
           {showJoinKeyHelp && (
             <div className={styles.helpText}>
               <p>
-                jsPsych experiments sometimes produce <strong>nested data</strong> — for example,
-                a survey trial might contain multiple responses stored as an array inside a single row.
-                To save this as a flat table (CSV), each nested item needs to be matched back to
-                its parent row.
+                Some jsPsych trials store a whole list inside one row — a survey trial holding
+                several responses, for example. Psych-DS datasets are flat tables, so those lists
+                get pulled out into their own CSV files, and every extracted row needs a way to
+                point back to the trial it came from.
               </p>
               <p>
-                A <strong>join key</strong> is a column (or combination of columns) whose values
-                are unique for every row, so that nested items can be correctly linked.{' '}
-                <code>trial_index</code> works fine in single-participant files, but if you merged
-                data from multiple participants, each participant resets <code>trial_index</code>{' '}
-                to 0 — making it non-unique. Adding a column like <code>subject</code> restores
-                uniqueness.
+                A <strong>join key</strong> is the column, or combination of columns, that does
+                this. Its values have to be different for every row.{' '}
+                <code>trial_index</code> is enough on its own in a single-participant file. But
+                once you merge several participants together it starts over at 0 for each of them,
+                so it no longer identifies a row by itself — adding something like{' '}
+                <code>subject</code> fixes that.
               </p>
             </div>
           )}
@@ -801,7 +812,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
                 onChange={() => { setProceedAnyway(p => !p); setSelectedKeys(['trial_index']); }}
               />
               <span className={styles.proceedLabel}>
-                Proceed anyway — extracted CSVs may have duplicate rows
+                Continue without one — the extracted files may contain duplicate rows
               </span>
             </li>
           </ul>
@@ -823,10 +834,19 @@ const DataUpload: React.FC<DataUploadProps> = ({
           <p className={styles.processSummary} aria-live="polite">
             {(() => {
               const total = fileStatuses.length;
-              const done = fileStatuses.filter(s => s.status !== 'pending' && s.status !== 'loading').length;
-              return phase === 'processing'
-                ? `Processing… ${done} of ${total} file${total !== 1 ? 's' : ''} processed.`
-                : `Done. ${done} of ${total} file${total !== 1 ? 's' : ''} processed.`;
+              if (phase === 'processing') {
+                const done = fileStatuses.filter(s => s.status !== 'pending' && s.status !== 'loading').length;
+                return `Processing… ${done} of ${total} file${total !== 1 ? 's' : ''} done.`;
+              }
+              // Report the outcome, not just the count: "4 of 4 processed" reads as success even
+              // when some of those four were skipped or failed.
+              const count = (status: FileStatus['status']) =>
+                fileStatuses.filter(s => s.status === status).length;
+              const read = count('success');
+              const parts = [`${read} file${read !== 1 ? 's' : ''} read`];
+              if (count('skipped') > 0) parts.push(`${count('skipped')} skipped`);
+              if (count('error') > 0) parts.push(`${count('error')} could not be read`);
+              return `Finished. ${parts.join(', ')}.`;
             })()}
           </p>
           <ul className={styles.statusList}>
@@ -848,7 +868,7 @@ const DataUpload: React.FC<DataUploadProps> = ({
           </button>
           {joinKeyCandidates.length > 0 && (
             <button className={styles.reConfigureBtn} onClick={() => enterReConfigureJoinKeys('done')}>
-              Re-configure join keys
+              Change join keys
             </button>
           )}
         </div>
diff --git a/packages/frontend/src/pages/Landing.tsx b/packages/frontend/src/pages/Landing.tsx
index 07add75..5ffcadb 100644
--- a/packages/frontend/src/pages/Landing.tsx
+++ b/packages/frontend/src/pages/Landing.tsx
@@ -68,7 +68,7 @@ const Landing: React.FC<LandingProps> = ({ onStart, embedded = false }) => {
           <span className={styles.cardIcon}>+</span>
           <span className={styles.cardTitle}>Create new project</span>
           <span className={styles.cardDesc}>
-            Start from scratch with your experiment data files
+            Start from scratch with the data files from your experiment
           </span>
         </button>
 
@@ -76,7 +76,7 @@ const Landing: React.FC<LandingProps> = ({ onStart, embedded = false }) => {
           <span className={styles.cardIconAmber}>↑</span>
           <span className={styles.cardTitle}>Open existing project</span>
           <span className={styles.cardDesc}>
-            Upload a <code>dataset_description.json</code> to continue editing
+            Upload a <code>dataset_description.json</code> you generated before, to keep editing it
           </span>
         </button>
       </div>
diff --git a/packages/frontend/src/pages/ProjectInfo.tsx b/packages/frontend/src/pages/ProjectInfo.tsx
index 79c030d..08d3ebd 100644
--- a/packages/frontend/src/pages/ProjectInfo.tsx
+++ b/packages/frontend/src/pages/ProjectInfo.tsx
@@ -3,14 +3,14 @@ import JsPsychMetadata from '@jspsych/metadata';
 import styles from './ProjectInfo.module.css';
 
 export const OPTIONAL_FIELDS: { key: string; label: string; hint: string; help?: string; options?: readonly string[] }[] = [
-  { key: 'license',    label: 'License',    hint: 'URL or SPDX identifier for the license', help: 'A license tells others what they can do with your data. Common choices for open research data: CC0 (public domain — no restrictions), CC-BY-4.0 (free to use with attribution). You can enter a standard identifier (e.g. CC-BY-4.0) or a URL to the full license text. If your institution has a data-sharing policy, check there first.' },
-  { key: 'keywords',   label: 'Keywords',   hint: 'Comma-separated keywords to assist search' },
-  { key: 'citation',   label: 'Citation',   hint: 'How to cite this dataset (URL or scholarly reference)' },
-  { key: 'url',        label: 'URL',        hint: 'Canonical source URL for this dataset' },
-  { key: 'funder',     label: 'Funder',     hint: 'Source(s) of funding — grant numbers or organization names' },
-  { key: 'identifier', label: 'Identifier', hint: 'Unique identifier such as a DOI or PMID' },
-  { key: 'privacyPolicy', label: 'Privacy policy', hint: 'How data access is restricted for this dataset', options: ['', 'open', 'private', 'open_deidentified', 'open_redacted'],
-    help: 'Choose the option that matches your IRB approval or data-sharing agreement:\n• open — data can be shared publicly without restriction\n• open_deidentified — data can be shared after removing directly identifying information (names, dates of birth, etc.)\n• open_redacted — data can be shared after removing specific sensitive fields\n• private — data is not to be shared outside your team' },
+  { key: 'license',    label: 'License',    hint: 'A standard license name like CC-BY-4.0, or a link to the license text', help: 'A license tells others what they may do with your data. Common choices for open research data: CC0 (public domain — no restrictions) and CC-BY-4.0 (free to use as long as you are credited). Enter the short name (e.g. CC-BY-4.0) or a link to the full text. If your institution has a data-sharing policy, check there first.' },
+  { key: 'keywords',   label: 'Keywords',   hint: 'Terms that help people find this dataset, separated by commas (e.g. stroop, attention)' },
+  { key: 'citation',   label: 'Citation',   hint: 'How you would like this dataset cited — a reference or a link' },
+  { key: 'url',        label: 'URL',        hint: 'Where this dataset lives online (e.g. its OSF page)' },
+  { key: 'funder',     label: 'Funder',     hint: 'Who funded the work — organization names, grant numbers, or both' },
+  { key: 'identifier', label: 'Identifier', hint: 'A permanent ID for this dataset, such as a DOI' },
+  { key: 'privacyPolicy', label: 'Sharing restrictions', hint: 'Who this dataset may be shared with. Saved as privacyPolicy.', options: ['', 'open', 'private', 'open_deidentified', 'open_redacted'],
+    help: 'Pick the option that matches your IRB approval or data-sharing agreement:\n• open — can be shared publicly, as is\n• open_deidentified — can be shared once directly identifying information (names, dates of birth, and so on) is removed\n• open_redacted — can be shared once specific sensitive fields are removed\n• private — must not leave your team' },
 ];
 
 export type MetadataLoadStatus = 'idle' | 'loading' | 'loaded' | 'error';
@@ -123,7 +123,7 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
         setLoadStatus('loaded');
       } catch {
         setLoadStatus('error');
-        setError('Failed to parse the metadata file — check that it is valid JSON.');
+        setError("We couldn't read that metadata file. Check that it is valid JSON, then try again.");
         // Record the attempt (so it isn't retried) and propagate the failure so the Data step
         // isn't pre-completed or shown as "variables loaded from existing metadata".
         onSessionChange({ ...session, loadStatus: 'error', loadToken: fileToken });
@@ -131,7 +131,7 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
     };
     reader.onerror = () => {
       setLoadStatus('error');
-      setError('Failed to read the file.');
+      setError("We couldn't read that file. Try choosing it again.");
       onSessionChange({ ...session, loadStatus: 'error', loadToken: fileToken });
     };
     reader.readAsText(existingMetadataFile);
@@ -189,14 +189,14 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
           applyUpload(parsed, true);
         }
       } catch {
-        setError('Could not parse the uploaded JSON file — check that it is valid.');
+        setError("We couldn't read that JSON file. Check that it is valid JSON, then try again.");
       }
     };
     reader.readAsText(file);
   };
 
   const handleContinue = () => {
-    if (!session.name.trim()) { setError('Project name is required.'); return; }
+    if (!session.name.trim()) { setError('Enter a project name to continue.'); return; }
     setError('');
     applyProjectInfoFields(jsPsychMetadata, session);
     onComplete();
@@ -242,15 +242,15 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
               aria-expanded={uploadHelpOpen}
               aria-label="Help for pre-fill from JSON"
             >ⓘ</button>
-            <span className={styles.uploadHint}>Populate fields from an existing metadata file</span>
+            <span className={styles.uploadHint}>Fill these fields from a metadata file you already have</span>
           </div>
           {uploadHelpOpen && (
             <div className={styles.helpBlock}>
-              Accepts any <code>.json</code> file that contains one or more of the following fields:
+              Any <code>.json</code> file will do, as long as it contains one or more of these fields:
               <br /><br />
               <code>name</code>, <code>description</code>, <code>license</code>, <code>keywords</code>, <code>citation</code>, <code>url</code>, <code>funder</code>, <code>identifier</code>, <code>privacyPolicy</code>
               <br /><br />
-              Array values (e.g. <code>"keywords": ["stroop", "rt"]</code>) are joined as comma-separated text. Unrecognized fields are ignored.
+              Lists (e.g. <code>"keywords": ["stroop", "rt"]</code>) become comma-separated text. Anything else in the file is ignored.
               <br /><br />
               Example:
               <pre className={styles.uploadHelpExample}>{`{
@@ -269,8 +269,8 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
             ? `"${conflictFields[0]}"`
             : conflictFields.map(f => `"${f}"`).join(' and ');
           const msg = count === 1
-            ? `The uploaded file has a different ${fieldStr} than what you've already entered.`
-            : `The uploaded file has different values for ${fieldStr} than what you've already entered.`;
+            ? `The file you uploaded has a different ${fieldStr} from the one you typed. Which would you like to keep?`
+            : `The file you uploaded has different values for ${fieldStr} from the ones you typed. Which would you like to keep?`;
           return (
             <div className={styles.conflictCallout}>
               <div className={styles.conflictMsgRow}>
@@ -307,10 +307,10 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
               )}
               <div className={styles.conflictBtns}>
                 <button type="button" className={styles.conflictYes} onClick={() => applyUpload(pendingUpload, true)}>
-                  Yes, overwrite
+                  Use the uploaded values
                 </button>
                 <button type="button" className={styles.conflictNo} onClick={() => applyUpload(pendingUpload, false)}>
-                  No, keep mine
+                  Keep what I typed
                 </button>
               </div>
             </div>
@@ -321,7 +321,7 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
           <label className={styles.label} htmlFor="project-name">
             Project name <span className={styles.required}>*</span>
           </label>
-          <p className={styles.hint}>The name of your dataset — any format works (e.g. StroopTask2024, my-stroop-experiment, stroop_study)</p>
+          <p className={styles.hint}>Names your dataset and the folder you download. Any style works (e.g. StroopTask2024, my-stroop-experiment, stroop_study)</p>
           <input
             id="project-name"
             className={styles.input}
@@ -352,7 +352,7 @@ const ProjectInfo: React.FC<ProjectInfoProps> = ({
               <em>Example: "Stroop task data from 40 undergraduates (20 control, 20 ADHD), measuring response time and accuracy across congruent and incongruent conditions."</em>
             </div>
           )}
-          <p className={styles.hint}>Briefly describe your dataset. If left blank, defaults to "No description provided."</p>
+          <p className={styles.hint}>Psych-DS requires a description, so leaving this blank records "No description provided."</p>
           <textarea
             id="project-description"
             className={styles.textarea}
diff --git a/packages/frontend/src/pages/Review.module.css b/packages/frontend/src/pages/Review.module.css
index db78405..b47562b 100644
--- a/packages/frontend/src/pages/Review.module.css
+++ b/packages/frontend/src/pages/Review.module.css
@@ -122,21 +122,6 @@
   line-height: 1.5;
 }
 
-.cliBlock {
-  margin: 0 0 0.75rem;
-  padding: 0.45rem 0.7rem;
-  background: var(--c-border-sub);
-  border: 1px solid var(--c-border);
-  border-radius: 5px;
-  font-family: 'Fira Code', 'Cascadia Code', monospace;
-  font-size: 0.82rem;
-  color: var(--c-ink-2);
-}
-
-.cliBlock:last-child {
-  margin-bottom: 0;
-}
-
 /* In-browser validation */
 
 .validateBtn {
@@ -261,21 +246,3 @@
   white-space: pre-wrap;
   word-break: break-word;
 }
-
-.cliAlt {
-  margin-top: 1rem;
-  border-top: 1px solid var(--c-border);
-  padding-top: 0.85rem;
-}
-
-.cliAltSummary {
-  font-size: 0.82rem;
-  font-weight: 500;
-  color: var(--c-ink-3);
-  cursor: pointer;
-  margin-bottom: 0.6rem;
-}
-
-.cliAltSummary:hover {
-  color: var(--c-ink-2);
-}
diff --git a/packages/frontend/src/pages/Review.tsx b/packages/frontend/src/pages/Review.tsx
index 77b7f7a..7aaa871 100644
--- a/packages/frontend/src/pages/Review.tsx
+++ b/packages/frontend/src/pages/Review.tsx
@@ -30,11 +30,6 @@ function sanitizeFilename(name: string): string {
   return cleaned || 'dataset';
 }
 
-// Warnings the downloadable zip already resolves: it ships a README.md and CHANGES.md the
-// in-browser validator can't see (it only checks the metadata + data files). When these show
-// up, we reassure the user rather than letting them think the dataset is incomplete.
-const ZIP_RESOLVED_WARNINGS = new Set(['MISSING_README_DOC', 'MISSING_CHANGES_DOC']);
-
 const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloaded }) => {
   const [downloaded, setDownloaded] = useState(false);
   const [zipped, setZipped] = useState(false);
@@ -110,7 +105,13 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
     try {
       // Lazy-loaded so the ~260 KB validator bundle stays out of the initial load.
       const { validatePsychDS } = await import('../validation/validatePsychDS');
-      const result = await validatePsychDS(metadataJson, dataFiles ?? undefined);
+      // hasDataFiles ⇒ the user downloads a zip, which ships README.md / CHANGES.md; pass the
+      // project name so those are validated alongside the metadata and data.
+      const result = await validatePsychDS(
+        metadataJson,
+        dataFiles ?? undefined,
+        hasDataFiles ? projectName : undefined,
+      );
       setValResult(result);
       setValStatus('done');
     } catch (err) {
@@ -118,7 +119,7 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
       setValError(
         err instanceof Error && err.name === 'ValidationUnavailableError'
           ? err.message
-          : `Validation failed unexpectedly: ${err instanceof Error ? err.message : String(err)}`,
+          : `Validation couldn't finish: ${err instanceof Error ? err.message : String(err)}`,
       );
       setValStatus('unavailable');
     }
@@ -162,7 +163,7 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
               </button>
               {usesFilePicker && !downloaded && (
                 <p className={styles.saveHint}>
-                  Navigate to your dataset folder in the save dialog so the file lands next to your <code className={styles.code}>data/</code> folder.
+                  In the save dialog, pick your existing dataset folder so this file sits next to your <code className={styles.code}>data/</code> folder.
                 </p>
               )}
             </div>
@@ -174,7 +175,7 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
             </button>
             {usesFilePicker && !downloaded && (
               <p className={styles.saveHint}>
-                Navigate to your dataset folder in the save dialog so the file lands next to your <code className={styles.code}>data/</code> folder — then it's ready to validate.
+                In the save dialog, pick your existing dataset folder so this file sits next to your <code className={styles.code}>data/</code> folder — then it's ready to validate.
               </p>
             )}
           </div>
@@ -185,8 +186,8 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
         <p className={styles.validatorTitle}>Validate your dataset</p>
         <p className={styles.validatorText}>
           Check this metadata{hasDataFiles ? ' and your data files' : ''} against the
-          Psych-DS standard right here. Validation runs in your browser and needs an
-          internet connection to fetch the schema.
+          Psych-DS standard without leaving the page. It runs in your browser, and needs
+          an internet connection to fetch the standard's schema.
         </p>
 
         <button
@@ -242,17 +243,10 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
             {valResult.warnings.length > 0 && (
               <>
                 <p className={styles.issueGroupLabel}>Warnings</p>
-                {hasDataFiles && valResult.warnings.some((w) => ZIP_RESOLVED_WARNINGS.has(w.key)) && (
-                  <p className={styles.warnNote}>
-                    Heads up: warnings about a missing <code className={styles.code}>README</code> or{' '}
-                    <code className={styles.code}>CHANGES</code> file are expected here — in-browser
-                    validation only checks the metadata and your data files. The{' '}
-                    <code className={styles.code}>{projectName}.zip</code> download already includes{' '}
-                    <code className={styles.code}>README.md</code> and{' '}
-                    <code className={styles.code}>CHANGES.md</code>, so these clear once you validate
-                    the downloaded dataset (e.g. with <code className={styles.code}>npx @jspsych/cli validate</code>).
-                  </p>
-                )}
+                <p className={styles.warnNote}>
+                  Warnings don't make a dataset invalid — they point at recommended metadata you
+                  haven't filled in.
+                </p>
                 <ul className={styles.issueList}>
                   {valResult.warnings.map((issue, i) => (
                     <li key={`w${i}`} className={`${styles.issueItem} ${styles.issueWarn}`}>
@@ -269,15 +263,6 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
           </>
         )}
         </div>
-
-        <details className={styles.cliAlt}>
-          <summary className={styles.cliAltSummary}>Prefer the command line?</summary>
-          <p className={styles.validatorText}>
-            Once <code className={styles.code}>dataset_description.json</code> is in your dataset folder, run:
-          </p>
-          <pre className={styles.cliBlock}>npx @jspsych/cli validate</pre>
-          <pre className={styles.cliBlock}>npx @jspsych/cli validate --psych-ds-dir ./your-dataset</pre>
-        </details>
       </div>
     </div>
     </>
diff --git a/packages/frontend/src/pages/Variables.tsx b/packages/frontend/src/pages/Variables.tsx
index 12bee39..0ae17d3 100644
--- a/packages/frontend/src/pages/Variables.tsx
+++ b/packages/frontend/src/pages/Variables.tsx
@@ -167,7 +167,7 @@ const Variables: React.FC<VariablesProps> = ({ jsPsychMetadata, onComplete }) =>
                 />
                 {hasPluginDesc && (
                   <p className={styles.descCaption}>
-                    From plugin documentation — edit to save a custom description
+                    From the plugin's documentation. Edit it to add your own wording.
                   </p>
                 )}
               </div>
@@ -227,7 +227,8 @@ const Variables: React.FC<VariablesProps> = ({ jsPsychMetadata, onComplete }) =>
       <div className={styles.page}>
         <div className={styles.introRow}>
           <p className={styles.subtext}>
-            Review and edit {vars.length} variable{vars.length === 1 ? '' : 's'} detected from your data.
+            {vars.length} variable{vars.length === 1 ? '' : 's'} found in your data. Click one to read
+            or change its description.
           </p>
           <label className={styles.toggleSwitch}>
             <span className={styles.toggleLabel}>Expand all</span>
diff --git a/packages/frontend/src/staging/datasetZip.ts b/packages/frontend/src/staging/datasetZip.ts
index 6b31805..94c1b8a 100644
--- a/packages/frontend/src/staging/datasetZip.ts
+++ b/packages/frontend/src/staging/datasetZip.ts
@@ -12,19 +12,13 @@
 // downloaded via an object URL.
 
 import { Zip, AsyncZipDeflate } from 'fflate';
-import { DATASET_DESCRIPTION_FILENAME } from '../datasetLayout';
+import { DATASET_DESCRIPTION_FILENAME, datasetDocs } from '../datasetLayout';
 import { blobDownload } from '../download';
 import type { DatasetFileSource } from './stagedFileStore';
 
 /** Slice size for feeding a file into the deflater — bounds peak heap to ~one slice per file. */
 const PUSH_CHUNK_BYTES = 1 << 20; // 1 MiB
 
-const readmeContents = (projectName: string): string =>
-  `# ${projectName}\nHuman-readable description of the project and dataset.`;
-
-const CHANGES_CONTENTS =
-  'For version tracking — if the dataset is updated after being uploaded/shared, changes (with human-readable descriptions) may be recorded here.';
-
 export interface BuildDatasetZipOptions {
   /** Serialized dataset_description.json (written at the archive root). */
   metadataJson: string;
@@ -100,8 +94,9 @@ async function buildZip(opts: BuildDatasetZipOptions, onChunk: (dat: Uint8Array)
             await addEntrySequential(path, blob);
           }
         }
-        await addEntrySequential('README.md', new Blob([readmeContents(opts.projectName)]));
-        await addEntrySequential('CHANGES.md', new Blob([CHANGES_CONTENTS]));
+        for (const { path, contents } of datasetDocs(opts.projectName)) {
+          await addEntrySequential(path, new Blob([contents]));
+        }
         zip.end();
       } catch (e) {
         fail(e);
diff --git a/packages/frontend/src/validation/validatePsychDS.ts b/packages/frontend/src/validation/validatePsychDS.ts
index 5d163cf..e89880b 100644
--- a/packages/frontend/src/validation/validatePsychDS.ts
+++ b/packages/frontend/src/validation/validatePsychDS.ts
@@ -4,7 +4,7 @@ import {
   type WebFileTree,
   type PsychDSValidationOutput,
 } from 'psychds-validator/web/psychds-validator.js';
-import { DATASET_DESCRIPTION_FILENAME as FILENAME } from '../datasetLayout';
+import { DATASET_DESCRIPTION_FILENAME as FILENAME, datasetDocs } from '../datasetLayout';
 import type { DatasetFileSource } from '../staging/stagedFileStore';
 
 export interface ValidationIssue {
@@ -59,6 +59,7 @@ function insertFile(tree: WebFileTree, path: string, file: Blob) {
 async function buildFileTree(
   metadataJson: string,
   dataFiles?: DatasetFileSource,
+  zipProjectName?: string,
 ): Promise<WebFileTree> {
   const tree: WebFileTree = {
     [FILENAME]: { type: 'file', file: new Blob([metadataJson]) },
@@ -70,6 +71,16 @@ async function buildFileTree(
       insertFile(tree, path, file);
     }
   }
+  // Validate the dataset the user is actually going to end up with. The zip download writes a
+  // placeholder README.md and CHANGES.md, so include the identical files here — otherwise the
+  // run reports MISSING_README_DOC / MISSING_CHANGES_DOC for documents the download does contain.
+  // Only when a zip is on offer: with no data files the user saves the bare metadata JSON, and
+  // those warnings are then real advice about their own folder.
+  if (zipProjectName !== undefined) {
+    for (const { path, contents } of datasetDocs(zipProjectName)) {
+      insertFile(tree, path, new Blob([contents]));
+    }
+  }
   return tree;
 }
 
@@ -78,24 +89,28 @@ async function buildFileTree(
  * metadata plus the user's data files. Requires network access — the validator
  * fetches the Psych-DS schema and schema.org context at runtime.
  *
- * @param metadataJson  Serialized dataset_description.json.
- * @param dataFiles     Lazy source of the Psych-DS `data/` payload: dataset-relative path
- *                      (e.g. `data/subject-sub01_data.csv`) -> file Blob, read one at a time.
+ * @param metadataJson    Serialized dataset_description.json.
+ * @param dataFiles       Lazy source of the Psych-DS `data/` payload: dataset-relative path
+ *                        (e.g. `data/subject-sub01_data.csv`) -> file Blob, read one at a time.
+ * @param zipProjectName  Project name when the user will download a zip, which ships placeholder
+ *                        README.md / CHANGES.md files — pass it so those are validated too. Omit
+ *                        when only the bare metadata JSON is being saved.
  */
 export async function validatePsychDS(
   metadataJson: string,
   dataFiles?: DatasetFileSource,
+  zipProjectName?: string,
 ): Promise<PsychDSValidationResult> {
   ensureJsonldGlobal();
 
-  const tree = await buildFileTree(metadataJson, dataFiles);
+  const tree = await buildFileTree(metadataJson, dataFiles, zipProjectName);
 
   let output: PsychDSValidationOutput;
   try {
     // 'latest' (rather than a pinned version) keeps results consistent with the
-    // CLI (`npx @jspsych/cli validate`) and the deployed web validator, which
-    // both use latest; pinning also risks requesting a schema version the
-    // schema server doesn't have, which would break validation outright.
+    // standalone validator (`npx psychds-validator`) and the deployed web
+    // validator, which both use latest; pinning also risks requesting a schema
+    // version the schema server doesn't have, which would break validation outright.
     output = await validateWeb(tree, { schema: 'latest' });
   } catch (err) {
     console.error('Psych-DS validation could not run:', err);
diff --git a/packages/frontend/tests/AppShellIntegration.test.tsx b/packages/frontend/tests/AppShellIntegration.test.tsx
index 38e310c..587b4a4 100644
--- a/packages/frontend/tests/AppShellIntegration.test.tsx
+++ b/packages/frontend/tests/AppShellIntegration.test.tsx
@@ -35,7 +35,7 @@ describe("AppShell + real ProjectInfo (existing project)", () => {
 
     // Continue — existing metadata is loaded, so Data is pre-completed and we skip to Variables.
     await userEvent.click(screen.getByRole("button", { name: "Continue →" }));
-    await screen.findByText(/Review and edit .* variables? detected/);
+    await screen.findByText(/variables? found in your data/);
 
     // Simulate an edit made on another step: delete a variable directly on the instance.
     meta.deleteVariable("rt");
@@ -58,14 +58,14 @@ describe("AppShell + real ProjectInfo (existing project)", () => {
 
     render(<AppShell jsPsychMetadata={meta} existingMetadataFile={badFile} onStartOver={jest.fn()} />);
 
-    await screen.findByText(/Failed to parse the metadata file/);
+    await screen.findByText(/We couldn.t read that metadata file/);
 
     // Continuing must land on the Data step (not skip it), and Data must NOT show the
     // "variables loaded from existing metadata" banner.
     await userEvent.type(screen.getByRole("textbox", { name: /Project name/ }), "Manual");
     await userEvent.click(screen.getByRole("button", { name: "Continue →" }));
 
-    expect(await screen.findByText(/Select your data folder/)).toBeInTheDocument();
+    expect(await screen.findByText(/Choose the folder holding your data files/)).toBeInTheDocument();
     expect(screen.queryByText(/Variables loaded from existing metadata/)).not.toBeInTheDocument();
   });
 });
diff --git a/packages/frontend/tests/Authors.test.tsx b/packages/frontend/tests/Authors.test.tsx
index fa7a5c0..e6b1298 100644
--- a/packages/frontend/tests/Authors.test.tsx
+++ b/packages/frontend/tests/Authors.test.tsx
@@ -226,7 +226,7 @@ describe("Authors", () => {
       await openOptional(card);
       meta.setAuthor.mockClear();
 
-      await userEvent.type(within(card).getByLabelText("@type"), "Person");
+      await userEvent.type(within(card).getByLabelText("Author type"), "Person");
       expect(meta.setAuthor).toHaveBeenCalledWith(
         expect.objectContaining({ "@type": "Person" }),
       );
@@ -333,7 +333,7 @@ describe("Authors", () => {
       );
       const call = meta.setAuthor.mock.calls[0][0] as AuthorFields;
       expect(call.identifier).toBeUndefined();
-      expect(screen.getByText(/ORCID not saved for: Jane Smith/)).toBeInTheDocument();
+      expect(screen.getByText(/their ORCID was not: Jane Smith/)).toBeInTheDocument();
     });
 
     test("warning can be dismissed", async () => {
@@ -341,7 +341,7 @@ describe("Authors", () => {
       await importLines("Jane Smith, bad-orcid");
 
       await userEvent.click(screen.getByRole("button", { name: "✕" }));
-      expect(screen.queryByText(/ORCID not saved for/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/their ORCID was not/)).not.toBeInTheDocument();
     });
   });
 
diff --git a/packages/frontend/tests/DataUpload.test.tsx b/packages/frontend/tests/DataUpload.test.tsx
index 370bea3..c054479 100644
--- a/packages/frontend/tests/DataUpload.test.tsx
+++ b/packages/frontend/tests/DataUpload.test.tsx
@@ -81,7 +81,7 @@ describe("DataUpload", () => {
   describe("idle phase", () => {
     test("renders description and picker buttons", () => {
       render(<DataUpload {...props()} />);
-      expect(screen.getByText(/Select your data folder/)).toBeInTheDocument();
+      expect(screen.getByText(/Choose the folder holding your data files/)).toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Choose folder" })).toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Upload .zip" })).toBeInTheDocument();
     });
@@ -98,7 +98,7 @@ describe("DataUpload", () => {
     test("shows variables-loaded banner, optional-upload note, and Continue", () => {
       render(<DataUpload {...props({ existingMetadataLoaded: true })} />);
       expect(screen.getByText(/Variables loaded from existing metadata/)).toBeInTheDocument();
-      expect(screen.getByText(/No data upload is needed/)).toBeInTheDocument();
+      expect(screen.getByText(/already describes every variable/)).toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Continue →" })).toBeInTheDocument();
     });
 
@@ -124,13 +124,13 @@ describe("DataUpload", () => {
     test("shows variable count and Continue button", () => {
       render(<DataUpload {...props({ jsPsychMetadata: makeMeta(["rt", "stimulus"]), dataProcessed: true })} />);
       expect(screen.getByText(/Data already processed/)).toBeInTheDocument();
-      expect(screen.getByText(/2 variables generated/)).toBeInTheDocument();
+      expect(screen.getByText(/2 variables found in your data/)).toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Continue →" })).toBeInTheDocument();
     });
 
     test("uses singular form for 1 variable", () => {
       render(<DataUpload {...props({ jsPsychMetadata: makeMeta(["rt"]), dataProcessed: true })} />);
-      expect(screen.getByText(/1 variable generated/)).toBeInTheDocument();
+      expect(screen.getByText(/1 variable found in your data/)).toBeInTheDocument();
     });
 
     test("shows file status list from session", () => {
@@ -146,14 +146,14 @@ describe("DataUpload", () => {
       expect(screen.getByText("parse failed")).toBeInTheDocument();
     });
 
-    test("shows Re-configure join keys when candidates and files exist", () => {
+    test("shows Change join keys when candidates and files exist", () => {
       const session: DataSession = {
         ...emptyDataSession,
         joinKeyCandidates: [{ column: "subject", makesUnique: true }],
         files: [makeFile("data.json", "[]")],
       };
       render(<DataUpload {...props({ dataProcessed: true, session })} />);
-      expect(screen.getByRole("button", { name: "Re-configure join keys" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Change join keys" })).toBeInTheDocument();
     });
   });
 
@@ -246,7 +246,7 @@ describe("DataUpload", () => {
         target: { files: [makeFile("empty.zip")] },
       });
 
-      expect(await screen.findByText(/No readable files found/)).toBeInTheDocument();
+      expect(await screen.findByText(/doesn.t contain any files we can read/)).toBeInTheDocument();
     });
 
     test("shows error when zip cannot be parsed", async () => {
@@ -256,7 +256,7 @@ describe("DataUpload", () => {
         target: { files: [makeFile("bad.zip")] },
       });
 
-      expect(await screen.findByText(/Could not read the zip file/)).toBeInTheDocument();
+      expect(await screen.findByText(/We couldn.t open that file/)).toBeInTheDocument();
     });
   });
 
@@ -312,7 +312,7 @@ describe("DataUpload", () => {
 
       render(<DataUpload {...props({ sampleSlug: "serial-reaction-time" })} />);
 
-      expect(await screen.findByText(/Could not load the .* dataset/)).toBeInTheDocument();
+      expect(await screen.findByText(/We couldn.t load the .* dataset/)).toBeInTheDocument();
       expect(screen.getByRole("button", { name: "Choose folder" })).toBeInTheDocument();
       expect(meta.generate).not.toHaveBeenCalled();
     });
@@ -342,22 +342,22 @@ describe("DataUpload", () => {
       );
     });
 
-    test("skips dataset_description.json with 'existing metadata file' detail", async () => {
+    test("skips dataset_description.json with a metadata-file detail", async () => {
       const { container } = render(<DataUpload {...props()} />);
       await pickAndProcess(makeFile("dataset_description.json", '{"name":"x"}'), container);
 
       await screen.findByRole("button", { name: "Continue →" });
       expect(meta.generate).not.toHaveBeenCalled();
-      expect(screen.getByText(/existing metadata file/)).toBeInTheDocument();
+      expect(screen.getByText(/this is a metadata file, not data/)).toBeInTheDocument();
     });
 
-    test("skips unsupported file types with 'unsupported file type' detail", async () => {
+    test("skips unsupported file types with an unsupported-type detail", async () => {
       const { container } = render(<DataUpload {...props()} />);
       await pickAndProcess(makeFile("notes.txt", "some text"), container);
 
       await screen.findByRole("button", { name: "Continue →" });
       expect(meta.generate).not.toHaveBeenCalled();
-      expect(screen.getByText(/unsupported file type/)).toBeInTheDocument();
+      expect(screen.getByText(/not a .csv, .json, or .jsonl file/)).toBeInTheDocument();
     });
 
     test("shows error status when generate throws", async () => {
@@ -377,7 +377,7 @@ describe("DataUpload", () => {
       await waitFor(() => expect(meta.generate).toHaveBeenCalledTimes(1));
       // generate() receives the parsed rows array, not the raw JSON string (parsed once up front).
       expect(meta.generate).toHaveBeenCalledWith(expect.any(Array), {}, "json", expect.any(Object));
-      expect(screen.queryByText(/Rows need a unique identifier/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/needs a column that tells its rows apart/)).not.toBeInTheDocument();
     });
 
     test("Continue button appears after done and calls onComplete", async () => {
@@ -461,13 +461,13 @@ describe("DataUpload", () => {
       const content = JSON.stringify([{ trial_index: 0, subject: "p1" }]);
       fireEvent.change(input, { target: { files: [makeFile("data.json", content)] } });
       await userEvent.click(screen.getByRole("button", { name: "Process files" }));
-      await screen.findByText(/Rows need a unique identifier/);
+      await screen.findByText(/needs a column that tells its rows apart/);
       return container;
     }
 
     test("shows warning and candidate columns when trial_index is non-unique", async () => {
       await renderToJoinKeys();
-      expect(screen.getByText(/Rows need a unique identifier/)).toBeInTheDocument();
+      expect(screen.getByText(/needs a column that tells its rows apart/)).toBeInTheDocument();
       expect(screen.getByText("subject")).toBeInTheDocument();
       expect(screen.getByText("sufficient alone")).toBeInTheDocument();
     });
@@ -475,13 +475,13 @@ describe("DataUpload", () => {
     test("help text expands and collapses", async () => {
       await renderToJoinKeys();
       const toggle = screen.getByRole("button", { name: /What is a join key/ });
-      expect(screen.queryByText(/nested data/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/store a whole list inside one row/)).not.toBeInTheDocument();
 
       await userEvent.click(toggle);
-      expect(screen.getByText(/nested data/)).toBeInTheDocument();
+      expect(screen.getByText(/store a whole list inside one row/)).toBeInTheDocument();
 
       await userEvent.click(toggle);
-      expect(screen.queryByText(/nested data/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/store a whole list inside one row/)).not.toBeInTheDocument();
     });
 
     test("selecting a column and applying calls generate with that key", async () => {
@@ -501,9 +501,9 @@ describe("DataUpload", () => {
       );
     });
 
-    test('"Proceed anyway" disables candidates and suppresses the warning', async () => {
+    test('"Continue without one" disables candidates and suppresses the warning', async () => {
       await renderToJoinKeys([{ column: "subject", makesUnique: true }]);
-      const proceedItem = screen.getByText(/Proceed anyway/).closest("li")!;
+      const proceedItem = screen.getByText(/Continue without one/).closest("li")!;
       await userEvent.click(within(proceedItem).getByRole("checkbox"));
 
       expect(within(screen.getByText("subject").closest("li")!).getByRole("checkbox")).toBeDisabled();
@@ -523,18 +523,18 @@ describe("DataUpload", () => {
       await userEvent.click(screen.getByRole("button", { name: "Cancel" }));
 
       expect(screen.getByRole("button", { name: "Process files" })).toBeInTheDocument();
-      expect(screen.queryByText(/Rows need a unique identifier/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/needs a column that tells its rows apart/)).not.toBeInTheDocument();
       expect(meta.generate).not.toHaveBeenCalled();
     });
 
-    test("Re-configure join keys button appears in the done phase after processing", async () => {
+    test("Change join keys button appears in the done phase after processing", async () => {
       await renderToJoinKeys([{ column: "subject", makesUnique: true }]);
       await userEvent.click(screen.getByRole("button", { name: "Apply and process files" }));
 
       // After applying, processing completes and phase becomes 'done'.
       // joinKeyCandidates is non-empty, so the Re-configure button should appear.
       expect(
-        await screen.findByRole("button", { name: "Re-configure join keys" }),
+        await screen.findByRole("button", { name: "Change join keys" }),
       ).toBeInTheDocument();
     });
   });
diff --git a/packages/frontend/tests/PreviewDrawer.test.tsx b/packages/frontend/tests/PreviewDrawer.test.tsx
index 3f84b66..8b501d6 100644
--- a/packages/frontend/tests/PreviewDrawer.test.tsx
+++ b/packages/frontend/tests/PreviewDrawer.test.tsx
@@ -44,7 +44,7 @@ describe("PreviewDrawer", () => {
 
   test("clicking inside the dialog content does not close it", async () => {
     render(<PreviewDrawer jsPsychMetadata={makeMeta({ name: "x" })} onClose={onClose} />);
-    await userEvent.click(screen.getByText("JSON Preview"));
+    await userEvent.click(screen.getByText("JSON preview"));
     expect(onClose).not.toHaveBeenCalled();
   });
 
diff --git a/packages/frontend/tests/ProjectInfo.test.tsx b/packages/frontend/tests/ProjectInfo.test.tsx
index ffe603a..60bdff9 100644
--- a/packages/frontend/tests/ProjectInfo.test.tsx
+++ b/packages/frontend/tests/ProjectInfo.test.tsx
@@ -78,7 +78,7 @@ describe("ProjectInfo", () => {
       );
       await userEvent.click(screen.getByRole("button", { name: "Continue →" }));
 
-      expect(screen.getByText("Project name is required.")).toBeInTheDocument();
+      expect(screen.getByText("Enter a project name to continue.")).toBeInTheDocument();
       expect(onComplete).not.toHaveBeenCalled();
     });
 
@@ -168,7 +168,7 @@ describe("ProjectInfo", () => {
           onComplete={onComplete}
         />,
       );
-      expect(screen.getByLabelText("Privacy policy")).toBeInstanceOf(HTMLSelectElement);
+      expect(screen.getByLabelText("Sharing restrictions")).toBeInstanceOf(HTMLSelectElement);
     });
 
     test("changing an optional field calls onSessionChange", async () => {
@@ -233,7 +233,7 @@ describe("ProjectInfo", () => {
       );
       const btn = screen.getByRole("button", { name: "Help for pre-fill from JSON" });
       await userEvent.click(btn);
-      expect(screen.getByText(/Array values/)).toBeInTheDocument();
+      expect(screen.getByText(/Lists \(e\.g\./)).toBeInTheDocument();
 
       await userEvent.click(btn);
       expect(screen.queryByText(/Array values/)).not.toBeInTheDocument();
@@ -293,8 +293,8 @@ describe("ProjectInfo", () => {
       uploadJson(container, { name: "Uploaded" });
 
       expect(await screen.findByText(/different "name"/)).toBeInTheDocument();
-      expect(screen.getByRole("button", { name: "Yes, overwrite" })).toBeInTheDocument();
-      expect(screen.getByRole("button", { name: "No, keep mine" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Use the uploaded values" })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: "Keep what I typed" })).toBeInTheDocument();
     });
 
     test("conflict: 'See details' expands current vs uploaded comparison", async () => {
@@ -313,7 +313,7 @@ describe("ProjectInfo", () => {
       expect(screen.getByText("Different Name")).toBeInTheDocument();
     });
 
-    test("conflict: 'Yes, overwrite' calls onSessionChange with uploaded values", async () => {
+    test("conflict: 'Use the uploaded values' calls onSessionChange with uploaded values", async () => {
       const { container } = render(
         <ProjectInfo
           jsPsychMetadata={meta}
@@ -323,15 +323,15 @@ describe("ProjectInfo", () => {
         />,
       );
       uploadJson(container, { name: "Uploaded" });
-      await userEvent.click(await screen.findByRole("button", { name: "Yes, overwrite" }));
+      await userEvent.click(await screen.findByRole("button", { name: "Use the uploaded values" }));
 
       expect(onSessionChange).toHaveBeenCalledWith(
         expect.objectContaining({ name: "Uploaded" }),
       );
-      expect(screen.queryByRole("button", { name: "Yes, overwrite" })).not.toBeInTheDocument();
+      expect(screen.queryByRole("button", { name: "Use the uploaded values" })).not.toBeInTheDocument();
     });
 
-    test("conflict: 'No, keep mine' applies optional fields but keeps current name", async () => {
+    test("conflict: 'Keep what I typed' applies optional fields but keeps current name", async () => {
       const { container } = render(
         <ProjectInfo
           jsPsychMetadata={meta}
@@ -341,7 +341,7 @@ describe("ProjectInfo", () => {
         />,
       );
       uploadJson(container, { name: "Uploaded", license: "CC0" });
-      await userEvent.click(await screen.findByRole("button", { name: "No, keep mine" }));
+      await userEvent.click(await screen.findByRole("button", { name: "Keep what I typed" }));
 
       const call = onSessionChange.mock.calls.at(-1)?.[0] as ProjectInfoSession;
       expect(call.name).toBe("Existing");
diff --git a/packages/frontend/tests/Review.test.tsx b/packages/frontend/tests/Review.test.tsx
index a555ec9..a02eb8a 100644
--- a/packages/frontend/tests/Review.test.tsx
+++ b/packages/frontend/tests/Review.test.tsx
@@ -93,9 +93,12 @@ describe("Review", () => {
     await userEvent.click(screen.getByRole("button", { name: "Validate dataset" }));
 
     expect(await screen.findByText("✓ Valid Psych-DS dataset")).toBeInTheDocument();
+    // The third argument is the project name, passed only when a zip download is on offer, so
+    // the validator also sees the README.md / CHANGES.md that zip will contain.
     expect(mockValidate).toHaveBeenCalledWith(
       expect.stringContaining('"my-project"'),
       dataFiles,
+      "my-project",
     );
     // Button switches to re-validate after a run.
     expect(screen.getByRole("button", { name: "Re-validate" })).toBeInTheDocument();
@@ -127,25 +130,10 @@ describe("Review", () => {
     expect(screen.getByText("MISSING_README")).toBeInTheDocument();
   });
 
-  test("explains that README/CHANGES warnings are resolved by the zip download", async () => {
-    mockValidate.mockResolvedValue({
-      valid: true,
-      errors: [],
-      warnings: [
-        { key: "MISSING_README_DOC", reason: "include a README", evidence: [] },
-        { key: "MISSING_CHANGES_DOC", reason: "include a CHANGES", evidence: [] },
-      ],
-    });
-    const dataFiles = await storeWith([["data/subject-sub01_data.csv", "a,b\n1,2"]]);
-    render(<Review jsPsychMetadata={makeMetadata()} dataFiles={dataFiles} />);
-    await userEvent.click(screen.getByRole("button", { name: "Validate dataset" }));
-
-    expect(await screen.findByText(/already includes/)).toHaveTextContent(
-      /README\.md.*CHANGES\.md/,
-    );
-  });
-
-  test("omits the README/CHANGES note when there is no zip (no data files)", async () => {
+  // With no data files the user saves the bare metadata JSON — no zip, so no README.md/CHANGES.md
+  // are produced and those warnings are genuine advice about their own folder. The project name is
+  // withheld in that case so the validator does not see documents that will not exist.
+  test("withholds the project name from validation when there is no zip (no data files)", async () => {
     mockValidate.mockResolvedValue({
       valid: true,
       errors: [],
@@ -155,7 +143,7 @@ describe("Review", () => {
     await userEvent.click(screen.getByRole("button", { name: "Validate dataset" }));
 
     await screen.findByText("MISSING_README_DOC");
-    expect(screen.queryByText(/already includes/)).not.toBeInTheDocument();
+    expect(mockValidate).toHaveBeenCalledWith(expect.any(String), undefined, undefined);
   });
 
   test("shows the validator's own message when validation is unavailable", async () => {
@@ -176,13 +164,8 @@ describe("Review", () => {
     await userEvent.click(screen.getByRole("button", { name: "Validate dataset" }));
 
     expect(
-      await screen.findByText("Validation failed unexpectedly: boom"),
+      await screen.findByText("Validation couldn't finish: boom"),
     ).toBeInTheDocument();
   });
 
-  test("keeps the CLI instructions available as a fallback", () => {
-    render(<Review jsPsychMetadata={makeMetadata()} />);
-    expect(screen.getByText("Prefer the command line?")).toBeInTheDocument();
-    expect(screen.getByText("npx @jspsych/cli validate")).toBeInTheDocument();
-  });
 });
diff --git a/packages/frontend/tests/Variables.test.tsx b/packages/frontend/tests/Variables.test.tsx
index 0a016d9..4b4f818 100644
--- a/packages/frontend/tests/Variables.test.tsx
+++ b/packages/frontend/tests/Variables.test.tsx
@@ -93,7 +93,7 @@ describe("Variables", () => {
     test("renders the total variable count in the intro text", () => {
       const meta = makeMeta([unknownVar("rt"), knownVar("stimulus")]);
       render(<Variables jsPsychMetadata={meta} onComplete={onComplete} />);
-      expect(screen.getByText(/2 variables detected/)).toBeInTheDocument();
+      expect(screen.getByText(/2 variables found in your data/)).toBeInTheDocument();
     });
 
     test("renders cleanly with zero variables", () => {
@@ -291,7 +291,7 @@ describe("Variables", () => {
 
       await userEvent.click(within(varRow("rt")).getByRole("button")); // expand
       expect(
-        within(varRow("rt")).getByText(/From plugin documentation/),
+        within(varRow("rt")).getByText(/From the plugin's documentation/),
       ).toBeInTheDocument();
     });
   });
diff --git a/packages/frontend/tests/validatePsychDS.test.ts b/packages/frontend/tests/validatePsychDS.test.ts
index 2dbf890..e9a53ee 100644
--- a/packages/frontend/tests/validatePsychDS.test.ts
+++ b/packages/frontend/tests/validatePsychDS.test.ts
@@ -69,6 +69,28 @@ describe("validatePsychDS", () => {
     await expect(blobText(raw.contents["sub01.json"].file)).resolves.toBe("[]");
   });
 
+  // The zip download ships placeholder README.md / CHANGES.md. Validating without them reported
+  // MISSING_README_DOC / MISSING_CHANGES_DOC against documents the download actually contains, so
+  // the tree carries the same two files whenever a zip is what the user will get.
+  test("includes the zip's README/CHANGES placeholders when a project name is given", async () => {
+    mockValidateWeb.mockResolvedValue(validatorOutput([]));
+    await validatePsychDS("{}", undefined, "my-study");
+
+    const [tree] = mockValidateWeb.mock.calls[0];
+    expect(tree["README.md"].type).toBe("file");
+    expect(tree["CHANGES.md"].type).toBe("file");
+    await expect(blobText(tree["README.md"].file)).resolves.toContain("# my-study");
+  });
+
+  test("omits README/CHANGES when only the bare metadata file is being saved", async () => {
+    mockValidateWeb.mockResolvedValue(validatorOutput([]));
+    await validatePsychDS("{}");
+
+    const [tree] = mockValidateWeb.mock.calls[0];
+    expect(tree["README.md"]).toBeUndefined();
+    expect(tree["CHANGES.md"]).toBeUndefined();
+  });
+
   test("reports valid when the validator finds no issues", async () => {
     mockValidateWeb.mockResolvedValue(validatorOutput([]));
     const result = await validatePsychDS("{}");
diff --git a/website/docs/guides/customizing-output.md b/website/docs/guides/customizing-output.md
index 7ea6729..28ee1df 100644
--- a/website/docs/guides/customizing-output.md
+++ b/website/docs/guides/customizing-output.md
@@ -6,13 +6,13 @@ description: Add authors, descriptions, and variable details to the generated da
 
 # Customizing the output
 
-The [web wizard](/wizard) collects extra information — authors, a dataset description, variable descriptions — through its on-screen forms. The CLI has no forms, so you supply that same information as a JSON **options file**: the command-line equivalent of filling in those fields.
+The [web wizard](/wizard) asks for the details it can't work out from your data — authors, a dataset description, descriptions for unfamiliar columns — using on-screen forms. The CLI has no forms, so you write that same information into a JSON **options file** and hand it over.
 
 Pass it with the [`--metadata-options` flag](../reference/cli-reference.md#flags), or choose **Use a custom metadata file** when the CLI prompts you.
 
 ## File format
 
-A plain JSON file (any name, anywhere). Each top-level key maps to a field in `dataset_description.json`; two keys have special handling (`author` and `variables`), and everything else is written through directly.
+A plain JSON file — call it what you like and keep it wherever you like. Each key in it corresponds to a field in `dataset_description.json`. Two keys, `author` and `variables`, get special treatment (covered below); every other key is copied into the metadata as-is.
 
 ```json
 {
@@ -37,7 +37,7 @@ You only need to include what you want to add or override — everything else is
 
 ## Top-level fields
 
-Any key other than `author` or `variables` is written straight through. Commonly used ones:
+The ones people use most:
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -53,21 +53,21 @@ These map to [Schema.org Dataset](https://schema.org/Dataset) properties; any va
 
 ## Author fields
 
-The `author` key takes an object where each entry is one author, keyed by their display name (also used as `name` if you don't set it explicitly).
+Under `author`, each entry is one person. The label you give the entry (`"Alex Johnson"` in the example above) is their display name, and every field inside it is optional.
 
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | inferred | Full name. Defaults to the author's key if omitted. |
-| `givenName` | no | First name. |
-| `familyName` | no | Last name. |
-| `identifier` | no | A persistent identifier URL, such as an [ORCID](https://orcid.org/). |
+| Field | Description |
+|-------|-------------|
+| `name` | Full name. If you leave it out, the entry's label is used. |
+| `givenName` | First name. |
+| `familyName` | Last name. |
+| `identifier` | A permanent link to the person, such as an [ORCID](https://orcid.org/). |
 
 ## Variable fields
 
-The `variables` key enriches or overrides variable metadata auto-generated from your data. Each entry is keyed by the exact column name.
+Use `variables` to add to or correct what the tool worked out from your data. Label each entry with the column name exactly as it appears in your files.
 
 :::note
-Variables listed here must already exist in your data — the options file can update entries the tool generated, not create new ones.
+This file updates entries the tool generated — it can't create variables that aren't in your data.
 :::
 
 ```json
@@ -87,21 +87,21 @@ Variables listed here must already exist in your data — the options file can u
 }
 ```
 
-Descriptions use a source-keyed object: use `"user"` for text you write yourself. Your entry appears *alongside* any plugin-fetched description rather than replacing it, so the final field shows both. To replace one outright, edit `dataset_description.json` after generation.
+Notice that `description` isn't plain text — it's wrapped in `{ "user": … }`. That label records where the description came from, so what you write sits *next to* the plugin's version rather than replacing it. Always use `"user"` for your own text. To keep only your version, edit `dataset_description.json` after generating it.
 
-Accepted variable fields:
+The fields you can set on a variable:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `description` | object | Source-keyed description (see above). |
+| `description` | object | What the column means, written as `{ "user": "…" }` (see above). |
 | `minValue` / `maxValue` | number | Expected range for numeric variables. |
 | `levels` | array | Possible values for categorical variables. |
 | `levelsOrdered` | boolean | Whether `levels` has a meaningful order (e.g. a Likert scale). |
-| `na` | boolean | Whether missing values are present. |
-| `naValue` | string | The string used for missing values (e.g. `"NA"`, `"999"`). |
-| `alternateName` | string | An alternative name or abbreviation. |
-| `identifier` | string | A URL pointing to a formal definition of the variable. |
-| `privacy` | string | Notes on the sensitivity of the variable. |
+| `na` | boolean | Whether the column has missing values. |
+| `naValue` | string | What missing values look like in the data (e.g. `"NA"`, `"999"`). |
+| `alternateName` | string | Another name or abbreviation for the column. |
+| `identifier` | string | A link to a formal definition of the variable. |
+| `privacy` | string | Notes on how sensitive the column is. |
 
 :::tip
 Run the tool once **without** an options file, open `dataset_description.json` to see what was generated, then use the options file to fill the gaps and re-run. Custom descriptions persist across re-runs — updating a project reloads the existing file first.
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
index 223a2d9..a7e618c 100644
--- a/website/docs/guides/troubleshooting.md
+++ b/website/docs/guides/troubleshooting.md
@@ -11,50 +11,54 @@ Common issues when generating metadata with the web wizard or the CLI, and how t
 ## Validation
 
 **"Missing README" / "Missing CHANGES" warnings.**
-Expected when the wizard validates in the browser — those files aren't part of the in-browser check. The downloaded project includes both, so the warnings clear when you validate the unzipped folder with the [Psych-DS validator](https://psych-ds.github.io/validator/). Warnings do not cause validation to fail, but they may indicate recommended metadata is missing.
+The wizard includes a placeholder `README.md` and `CHANGES.md` in the project you download, and validates them along with everything else, so these warnings shouldn't appear there. You will see them if you save only `dataset_description.json`, or if you validate a folder of your own that has no such files — add the two files to clear them.
+
+More generally: warnings never make validation fail. They flag recommended metadata you haven't provided, so they're worth reading, but a dataset with warnings is still valid.
 
 **`JSON_KEY_REQUIRED: … missing required field(s)`.**
-Your `dataset_description.json` is missing a required field (often `description`). Fill it in on the wizard's Project info step; in the CLI running interactively you'll be prompted to add it before finishing. Add the field and generate again.
+Your `dataset_description.json` is missing a field Psych-DS requires — usually `description`. Fill it in on the wizard's Project info step, or, in the CLI, at the prompt that appears before it finishes. Then generate again.
 
 **`CSV_HEADER_MISSING`, or a file fails validation for an empty header.**
-An empty or header-less CSV in your data folder. Remove blank or 0-byte CSV files before running.
+One of your CSV files is empty or has no header row. Delete blank and 0-byte CSV files from your data folder, then run again.
 
 ## File names
 
 **"These filenames don't follow the Psych-DS pattern."**
-Psych-DS expects `keyword-value_data.csv` (e.g. `subject-01_data.csv`). In **interactive** mode the tool offers renaming strategies with a live preview on your real filenames; in **non-interactive** mode a non-compliant name is a hard error, so rename before running. See [Data file naming](../reference/cli-reference.md#data-file-naming).
+Psych-DS expects data files to be named `keyword-value_data.csv` (e.g. `subject-01_data.csv`). Normally the tool offers to rename them for you, showing a preview on your actual filenames first. The exception is a scripted run with no prompts, where a name that doesn't match is a hard error — rename the files yourself before running. See [Data file naming](../reference/cli-reference.md#data-file-naming).
 
 **A validator warning about an "unofficial keyword."**
-A name like `group-a_data.csv` is technically valid but uses a keyword outside the official set, which draws a warning. The tool offers to rename these too, or you can pick an [official keyword](../reference/cli-reference.md#data-file-naming) (`subject`, `session`, `task`, …).
+A name like `group-a_data.csv` is legal, but `group` isn't one of the keywords Psych-DS defines, so the validator mentions it. You can ignore it, let the tool rename the files, or switch to an [official keyword](../reference/cli-reference.md#data-file-naming) such as `subject`, `session`, or `task`.
 
 ## Files not picked up
 
 **Some files were ignored.**
-Only `.csv`, `.json`, and `.jsonl` files are processed; other types are skipped. The tool also reads the data folder and **one** level of subfolders — anything nested deeper is ignored. See [Folder depth](../reference/cli-reference.md#folder-depth).
+Two things to check: only `.csv`, `.json`, and `.jsonl` files are read, and the tool looks in your data folder plus **one** level of subfolders, so anything buried deeper is never seen. See [Folder depth](../reference/cli-reference.md#folder-depth).
 
 **A JSON file wasn't recognized.**
-JSON input must be a trial **array** (`[ {…}, {…} ]`) or the `{ "trials": [...] }` wrapper. A JSON object in any other shape is skipped. See [Accepted formats](../reference/cli-reference.md#accepted-formats).
+The tool expects a jsPsych trial list: either an array of trials (`[ {…}, {…} ]`) or the `{ "trials": [...] }` wrapper some services export. JSON in any other shape is skipped. See [Accepted formats](../reference/cli-reference.md#accepted-formats).
 
 ## Join keys (nested arrays)
 
 **The tool asks you to choose a "join key."**
-A file contains nested arrays (e.g. a survey trial holding several responses) and `trial_index` doesn't uniquely identify each row — common in merged multi-participant files where `trial_index` resets per person. Pick one or more columns marked **sufficient alone** until every row is unique, then continue. See [Nested arrays and join keys](../reference/cli-reference.md#nested-arrays-and-join-keys).
+One of your files stores a list inside a single trial, and the rows extracted from it need a column that points back to the trial they came from. `trial_index` normally does the job, but if you merged several participants into one file it restarts at 0 for each of them.
+
+Tick columns marked **sufficient alone** until every row is unique, then continue. See [Nested arrays and join keys](../reference/cli-reference.md#nested-arrays-and-join-keys).
 
 ## File formats and encoding
 
-**A CSV parses with a garbled first column name (e.g. `id`).**
-A UTF-8 byte-order mark (BOM) at the start of the file. The tools strip the BOM automatically; if you see this on an older version, update — or re-save the file as UTF-8 without a BOM.
+**A CSV's first column name comes out garbled (e.g. `id`).**
+Those stray characters are a byte-order mark, an invisible marker some programs write at the start of a file. Current versions remove it automatically, so update if you're on an older one — or re-save the file as UTF-8 without a byte-order mark.
 
 **A blank leading column disappeared.**
-The unnamed row-index column that some exporters and R prepend is dropped on purpose. This is expected, not data loss.
+That's the unnamed row-number column R and some export tools add. It's dropped on purpose, since it isn't data. Nothing of yours was lost.
 
 ## Variable descriptions
 
 **A variable's description is `unknown` or blank.**
-Descriptions are looked up from the jsPsych plugin that produced each column, so columns the tool doesn't recognize — custom fields, or data not produced by a plugin — have no automatic description. Fill them in on the wizard's Variables step, at the CLI's prompt, or with a [metadata options file](./customizing-output.md).
+Descriptions come from the jsPsych plugin that produced each column, so anything a plugin didn't produce — data you added yourself, or custom fields — has nothing to look up. Write those descriptions on the wizard's Variables step, at the CLI's prompt, or in a [metadata options file](./customizing-output.md).
 
-**Descriptions are missing for plugins you know have them.**
-Description lookup fetches plugin source over the network. If you're offline or the request is blocked, descriptions can't be retrieved — reconnect and run again, or add them manually.
+**Descriptions are missing for plugins you know document them.**
+Looking up a description means fetching the plugin's source over the internet. If you were offline, or a firewall blocked the request, nothing comes back. Reconnect and run again, or write those descriptions yourself.
 
 ---
 
diff --git a/website/docs/guides/using-the-cli.mdx b/website/docs/guides/using-the-cli.mdx
index 3f0526a..bcdf817 100644
--- a/website/docs/guides/using-the-cli.mdx
+++ b/website/docs/guides/using-the-cli.mdx
@@ -23,7 +23,7 @@ You'll need **Node.js 18+** (check with `node --version`; install from [nodejs.o
 npx @jspsych/metadata-cli
 ```
 
-The first run downloads the tool automatically; after that it launches immediately and starts asking the questions below. Every step is identical on **macOS, Windows, and Linux** — only the way you type a folder path differs (see step 5). Any modern terminal works: Terminal on macOS, PowerShell or Windows Terminal on Windows.
+The first run downloads the tool automatically; after that it launches immediately. Every step is identical on **macOS, Windows, and Linux** — only the way you type a folder path differs (see step 5). Any modern terminal works: Terminal on macOS, PowerShell or Windows Terminal on Windows.
 
 </Step>
 
@@ -91,7 +91,9 @@ The prompt is the same on every platform; only the path format differs.
 <details>
 <summary>Which file formats are accepted?</summary>
 
-**CSV**, a **JSON array** (`[ {…}, {…} ]`), the **`{ "trials": [...] }` wrapper** (e.g. OSF exports), or **JSON-Lines (`.jsonl`)**. JSON and JSON-Lines are converted to CSV in `data/`. CSV content is kept as-is where possible. Originals are preserved under `data/raw/` whenever the output is not a byte-for-byte, same-named copy of the input (converted JSON, re-serialised CSVs, renamed CSVs). Other file types are ignored.
+**CSV**, a **JSON array** (`[ {…}, {…} ]`), the **`{ "trials": [...] }` wrapper** (e.g. OSF exports), or **JSON-Lines (`.jsonl`)**. Anything else is ignored.
+
+JSON and JSON-Lines are converted to CSV in `data/`; CSV content is kept as-is where possible. Whenever a file has to change on the way in — a JSON file converted to CSV, or a CSV renamed or rewritten — the untouched original is also saved under `data/raw/`.
 
 </details>
 
@@ -191,7 +193,7 @@ If a **required field** is missing, it prompts you to supply it before finishing
 ```
 my-experiment/
 ├── data/                       Psych-DS compliant copies of your data
-│   └── raw/                     originals, if inputs were JSON/JSON-Lines
+│   └── raw/                     your untouched originals, if anything changed
 ├── dataset_description.json    generated metadata
 ├── README.md                   placeholder for a description
 └── CHANGES.md                  placeholder for a changelog
diff --git a/website/docs/guides/using-the-wizard.mdx b/website/docs/guides/using-the-wizard.mdx
index da6df6d..4a4aa68 100644
--- a/website/docs/guides/using-the-wizard.mdx
+++ b/website/docs/guides/using-the-wizard.mdx
@@ -16,11 +16,13 @@ When you open it, pick a starting point:
 - **Create new project** — start from scratch with your data files (the path below).
 - **Open existing project** — upload an existing `dataset_description.json` to keep editing it, or to refresh the metadata after collecting more data.
 
+At any point, the **`{}` Preview** button in the corner shows the metadata file as it stands so far.
+
 <Steps>
 
 <Step n={1} title="Project info">
 
-Give the dataset a **name** (required — it becomes the identifier and the downloaded folder name) and a plain-English **description**. Optional fields — license, funding source, keywords, citation — fill in the recommended Psych-DS metadata.
+Give the dataset a **name** (required — it identifies the dataset and names the folder you download) and a plain-English **description** of what it contains. The optional fields — license, funder, keywords, citation — cover the rest of the metadata Psych-DS recommends.
 
 <details>
 <summary>Starting from an existing project?</summary>
@@ -31,9 +33,9 @@ You can upload an existing `dataset_description.json` here to pre-fill every fie
 
 </Step>
 
-<Step n={2} title="Data — upload your raw data files">
+<Step n={2} title="Upload your data">
 
-Click **Choose folder** to pick a directory of data files, or **Upload zip** to upload a `.zip`. Each file shows a status indicator once it's processed. Your originals are never modified.
+Click **Choose folder** to pick the folder holding your data files, or **Upload .zip** if they're in an archive. Then click **Process files** — each file gets a ✓, a — (skipped), or a ✗ (couldn't be read) as it goes.
 
 <details>
 <summary>Which file formats can I upload?</summary>
@@ -43,16 +45,18 @@ Click **Choose folder** to pick a directory of data files, or **Upload zip** to
 - **`{ "trials": [...] }` wrapper** — e.g. OSF exports; unwrapped automatically.
 - **JSON-Lines (`.jsonl`)** — one JSON value per line.
 
-JSON and JSON-Lines are converted to Psych-DS-named CSV (e.g. `data/subject-sub01_data.csv`) so the validator and the downloaded zip see compliant tables. Your originals are preserved untouched under `data/raw/` whenever the staged output is not a byte-for-byte, same-named copy of the upload — converted JSON, re-serialised CSVs, and renamed CSVs alike.
+JSON and JSON-Lines are converted to CSV and given a Psych-DS name (e.g. `data/subject-sub01_data.csv`).
+
+Your original files are never modified. Whenever a file has to change on the way in — a JSON file converted to CSV, or a CSV renamed or rewritten — the untouched original is also saved under `data/raw/` in the download.
 
 </details>
 
 <details>
 <summary>What's a "join key" and when will I be asked for one?</summary>
 
-If your files contain **nested arrays** (e.g. a survey trial holding multiple responses), each nested item has to be matched back to its parent row to store it as a flat CSV. A **join key** is a column whose values are unique for every row.
+Some trials store a whole list inside a single row — a survey trial holding several responses, for example. Those lists get pulled out into their own CSV tables, and each extracted row needs a way to point back to the trial it came from. A **join key** is the column (or combination of columns) that does this: its values must be different for every row.
 
-The wizard checks whether `trial_index` uniquely identifies each row; if it doesn't (for example, merged multi-participant files where `trial_index` resets to 0 per person), a chooser appears. Columns tagged **sufficient alone** make every row unique by themselves (often `participant_id`); pick one or more until each row is uniquely identified, then **Apply and process files**. A **Re-configure join keys** button stays available if you need to change it later.
+The wizard tries `trial_index` first. If that isn't enough — most often because you merged several participants into one file, and `trial_index` starts over at 0 for each of them — it asks you to pick. Columns marked **sufficient alone** (often `participant_id`) are enough by themselves; tick columns until every row is unique, then choose **Apply and process files**. You can revisit the choice later with **Change join keys**.
 
 </details>
 
@@ -60,21 +64,22 @@ The wizard checks whether `trial_index` uniquely identifies each row; if it does
 
 <Step n={3} title="Variables">
 
-The wizard detects every variable in your data and looks up what each one means from the jsPsych plugin that produced it. Review the list and fill in anything it couldn't identify automatically.
+The wizard finds every variable in your data and looks up what each one means from the jsPsych plugin that produced it. Review the list and fill in anything it couldn't identify.
 
-- Variables with **unknown descriptions** appear expanded at the top; known ones start collapsed (**Expand all / Collapse all** toggles them).
-- Each row has a **Description** field and a **Type** dropdown — editing either updates the metadata immediately.
+- Anything it couldn't describe is grouped under **Missing descriptions** at the top, with a running count of how many you've filled in. Everything else sits under **Other variables**.
+- Click a variable to open it. It has a **Description** box and a **Type** dropdown; both save as you type.
+- Filling these in is optional.
 
 </Step>
 
 <Step n={4} title="Authors">
 
-Add the people who contributed to the dataset. Click **Add author**, type a name, and press Tab to commit it. Expand a row for optional fields: given/family name, author type, and ORCID.
+Add the people who contributed to the dataset — optional, and you can come back to it later. Type a name, then click away from the box to save it; use **+ Add another author** for the next one. Open **Optional fields** on a card to add an ORCID, and the rarely-needed given name, family name, and author type.
 
 <details>
 <summary>Adding lots of authors at once</summary>
 
-**Bulk import** lets you paste a list of names (one per line, optionally followed by an ORCID) to add many authors at once. Invalid ORCIDs are flagged with a warning.
+**+ Add multiple authors at once** lets you paste a list — one name per line, with an optional ORCID after a comma. Any ORCID that isn't in the `0000-0001-2345-6789` format is skipped, and the wizard tells you which names it affected.
 
 </details>
 
@@ -82,15 +87,19 @@ Add the people who contributed to the dataset. Click **Add author**, type a name
 
 <Step n={5} title="Review & download">
 
-Inspect the generated `dataset_description.json` in the syntax-highlighted preview, then download your project.
+Read through the generated `dataset_description.json`, go back to any step to change something, then download.
 
-- **Download `<project-name>.zip`** gives a complete Psych-DS project: `dataset_description.json`, `README.md`, `CHANGES.md`, and your `data/` folder. (No data files? A **Save `dataset_description.json`** button appears instead.)
-- **Validate dataset** runs the Psych-DS validator in your browser and lists any errors and warnings inline.
+- **Download `<project-name>.zip`** gives you a complete Psych-DS project: `dataset_description.json`, `README.md`, `CHANGES.md`, and your `data/` folder. (If you didn't upload any data, you get a **Save `dataset_description.json`** button instead.)
+- **Validate dataset** checks the result against Psych-DS right there in your browser and lists any errors and warnings. It needs an internet connection to fetch the standard's schema.
 
 <details>
-<summary>About the validation warnings</summary>
+<summary>Errors and warnings</summary>
+
+**Errors** have to be fixed — the dataset isn't Psych-DS compliant until they are. Each one names the rule it broke and the files or columns at fault.
+
+**Warnings** never make validation fail. They point at recommended metadata you haven't filled in — an optional field, a suggested folder — so treat them as a checklist rather than a problem.
 
-Missing `README` / `CHANGES` warnings are expected in the in-browser check — the downloaded zip includes both files, so they clear when you validate the unzipped folder with the [Psych-DS web validator](https://psych-ds.github.io/validator/). The **`{}` Preview** pill (on every step except Review) opens a live JSON snapshot at any time.
+The check covers exactly what you're about to download, `README.md` and `CHANGES.md` included, so there's no need to validate the project again afterwards.
 
 </details>
 
diff --git a/website/docs/introduction.md b/website/docs/introduction.md
index ee01cd0..841bd02 100644
--- a/website/docs/introduction.md
+++ b/website/docs/introduction.md
@@ -10,7 +10,7 @@ description: What the Psych-DS data standard is, what a compliant dataset looks
 
 The [jsPsych metadata tools](https://github.com/jspsych/metadata) turn raw experiment exports into a Psych-DS–compliant dataset and automatically document the variables produced by your plugins.
 
-Describing your data this way — a machine-readable file listing its variables, authors, and license that travels alongside the data — is what makes a dataset easy to share, archive, and reuse, and it is increasingly expected by journals and funders as part of open, [FAIR](https://www.go-fair.org/fair-principles/) data.
+Describing your data this way means shipping a machine-readable file alongside it, listing its variables, authors, and license. That is what makes a dataset easy to share, archive, and reuse — and journals and funders increasingly expect it as part of open, [FAIR](https://www.go-fair.org/fair-principles/) data.
 
 Psych-DS is a general standard, not limited to jsPsych: it has its own [specification](https://psychds-docs.readthedocs.io/en/latest/) and an official [web validator](https://psych-ds.github.io/validator/). These tools generate a compliant dataset for you and run that same validation, so you never have to apply the spec by hand.
 
@@ -20,8 +20,6 @@ If you collect data with [DataPipe](https://pipe.jspsych.org/), you may not need
 
 ## The two pieces of a compliant dataset
 
-A Psych-DS compliant dataset needs two things:
-
 1. **A standard folder layout** — data files live in a `data/` folder, named to a `keyword-value_data.csv` pattern (e.g. `subject-01_data.csv`) so each file's role is unambiguous.
 2. **A `dataset_description.json`** — a [Schema.org](https://schema.org/) description that travels with the data, listing every variable (`variableMeasured`) and what each one means.
 
@@ -45,7 +43,7 @@ You can always add to or override what's generated — authors, a study descript
 
 ## What the tools produce
 
-Either the wizard or the CLI produces a self-contained Psych-DS project. At its core is your data plus the generated metadata:
+Either the wizard or the CLI produces a self-contained Psych-DS project:
 
 ```
 your-project/
@@ -53,9 +51,13 @@ your-project/
 └── dataset_description.json    the generated metadata
 ```
 
-JSON and JSON-Lines exports are converted to CSV. Originals are preserved under `data/raw/` whenever the output is not a byte-for-byte, same-named copy of the input — converted JSON, re-serialised CSVs, and renamed CSVs alike; only a clean CSV kept verbatim under its own compliant name is not duplicated there. The project also includes placeholder `README.md` and `CHANGES.md` files — see [Using the CLI](./guides/using-the-cli.mdx) for the full layout.
+JSON and JSON-Lines exports are converted to CSV.
+
+Your original files are never modified. Whenever a file has to change on the way in — a JSON file converted to CSV, or a CSV renamed or rewritten — the untouched original is also saved under `data/raw/`.
+
+The project also includes placeholder `README.md` and `CHANGES.md` files — see [Using the CLI](./guides/using-the-cli.mdx) for the full layout.
 
 ## Get started
 
-- **[Open the web wizard](/wizard)** — do it in your browser, no install. → [Using the wizard](./guides/using-the-wizard.mdx)
-- **Command line** — `npx @jspsych/metadata-cli`, easy to script. → [Using the CLI](./guides/using-the-cli.mdx)
+- **[Open the web wizard](/wizard)** — runs in your browser, nothing to install. → [Using the wizard](./guides/using-the-wizard.mdx)
+- **Command line** — `npx @jspsych/metadata-cli`, if you'd rather script it. → [Using the CLI](./guides/using-the-cli.mdx)
diff --git a/website/docs/reference/cli-reference.md b/website/docs/reference/cli-reference.md
index ce1c786..333547f 100644
--- a/website/docs/reference/cli-reference.md
+++ b/website/docs/reference/cli-reference.md
@@ -14,7 +14,7 @@ This page documents all flags, exit codes, filename rules, and output behaviour
 npx @jspsych/metadata-cli [flags]
 ```
 
-With no flags, the tool runs interactively and prompts you for everything it needs. All flags are optional — any flag you omit will be filled in by a prompt at runtime.
+Every flag is optional. Whatever you don't pass on the command line, the tool asks you for as it runs — so with no flags at all, it simply prompts you for everything it needs.
 
 ## Flags
 
@@ -23,18 +23,18 @@ With no flags, the tool runs interactively and prompts you for everything it nee
 | `--psych-ds-dir` | `-em` | path | Path to an **existing** Psych-DS project folder. Must contain a `dataset_description.json`. Use this when updating a project you have already generated. |
 | `--data-dir` | `-d` | path | Path to the folder containing your raw jsPsych data files (`.csv`, `.json`, or `.jsonl`). |
 | `--metadata-options` | `-m` | path | Path to a metadata options `.json` file. See [Customizing the output](../guides/customizing-output.md). |
-| `--verbose` | `-v` | boolean | Print detailed output at each processing step. Shows plugin fetching, variable resolution, and full validation warnings. |
+| `--verbose` | `-v` | boolean | Print detail at every step: which plugins were fetched, how each variable was worked out, and the full validation warnings. |
 | `--version` | | boolean | Print the CLI version and exit. |
 
 ### Notes on flag behaviour
 
 - Paths can use `~` for your home directory (e.g. `--data-dir=~/experiments/raw`).
-- If a flag is provided but the path is invalid (or the `--metadata-options` file is not valid JSON), the tool exits immediately with a usage error (exit code `2`). It does **not** fall back to an interactive prompt — a flag you passed explicitly failing silently would hide mistakes in scripts.
-- `--psych-ds-dir` implies **update mode** — the tool loads the existing `dataset_description.json` before processing new data. Without this flag, the tool asks whether to create or update.
+- If you pass a flag but the path is wrong (or the `--metadata-options` file isn't valid JSON), the tool stops immediately with a usage error (exit code `2`). It deliberately does **not** fall back to asking you — a flag that quietly did nothing would hide typos in scripts.
+- `--psych-ds-dir` puts the tool in **update mode**: it loads the existing `dataset_description.json` before processing new data. Without the flag, it asks whether you're creating or updating.
 
 ## Non-interactive mode
 
-When all three path flags are provided and valid, every interactive prompt is skipped and the tool runs to completion without user input:
+When all three path flags are provided and valid, every prompt is skipped:
 
 ```
 npx @jspsych/metadata-cli \
@@ -45,25 +45,25 @@ npx @jspsych/metadata-cli \
 
 Non-interactive mode enforces stricter rules than interactive mode:
 
-- **Non-compliant filenames are a hard error.** In interactive mode, the tool offers a menu of renaming strategies to bring non-compliant filenames into the Psych-DS naming pattern. In non-interactive mode, a non-compliant filename causes the tool to exit immediately with an error message and exit code `2` (usage error). Rename your files before running (see [Data file naming](#data-file-naming) below).
+- **Non-compliant filenames are a hard error.** With no way to offer the renaming menu, the tool exits with code `2`. Rename your files first (see [Data file naming](#data-file-naming) below).
 - **Unknown variable descriptions are not prompted.** Variables the tool cannot automatically describe are left as `"unknown"` in the output.
 - **Join keys are resolved automatically.** When nested-array rows aren't uniquely identified by `trial_index`, the tool picks the keys deterministically instead of prompting, and reports the choice (see [Nested arrays and join keys](#nested-arrays-and-join-keys)).
 
-The tool also runs without prompting whenever it isn't attached to an interactive terminal (for example, piped output or a CI job), even if you omit some flags. In that case it keeps the generated metadata defaults unless `--metadata-options` is supplied. Non-interactive mode is useful for running the tool on a schedule, in a script, or on a remote machine.
+The tool also skips prompts whenever there's no one at a terminal to answer them — piped output, a CI job, a scheduled run — even if you omit some flags. In that case it keeps the metadata it generated on its own, unless you pass `--metadata-options`.
 
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
-| `0` | Completed successfully. Psych-DS validation passed (warnings are allowed). |
-| `1` | Unexpected internal error, or an interactive prompt was aborted (e.g. Ctrl+C). |
-| `2` | Usage error: bad flags, a flag pointing at a missing directory, an invalid or malformed JSON input (`--metadata-options`, `dataset_description.json`), or a non-compliant data filename in non-interactive mode. |
-| `3` | The generated dataset failed Psych-DS validation with one or more errors. |
-| `4` | Partial success: some data files could not be ingested. The metadata written covers only the files that succeeded. |
+| `0` | Finished successfully. Psych-DS validation passed (warnings are fine). |
+| `1` | Something went wrong internally, or you cancelled a prompt (e.g. Ctrl+C). |
+| `2` | Usage error: bad flags, a flag pointing at a folder that isn't there, malformed JSON (`--metadata-options`, `dataset_description.json`), or a non-compliant data filename in a run with no prompts. |
+| `3` | The dataset was generated but failed Psych-DS validation with one or more errors. |
+| `4` | Partial success: some data files couldn't be read. The metadata covers only the files that worked. |
 
-If a run both fails validation and has ingestion failures, validation takes precedence: the tool exits `3`. Any non-zero code means the output should not be trusted as a complete, valid Psych-DS dataset.
+If a run both fails validation and couldn't read some files, validation wins and the tool exits `3`. Treat any non-zero code as "don't trust this output as a complete, valid Psych-DS dataset yet."
 
-You can use the exit code in a shell script to distinguish failures:
+Branching on the exit code in a script:
 
 ```bash
 npx @jspsych/metadata-cli --psych-ds-dir=./project --data-dir=./data --metadata-options=./options.json
@@ -89,13 +89,25 @@ The tool accepts the following jsPsych data shapes:
 | **`{ "trials": [...] }` wrapper** | An object whose single key is `trials` holding the trial array (e.g. OSF exports). Automatically unwrapped, then treated as a JSON array. |
 | **JSON-Lines (`.jsonl`)** | One JSON value per line (JATOS and several labs export this way — often one participant's trial array per line). All lines are flattened into a single observation stream. |
 
-JSON and JSON-Lines files are automatically converted to CSV in the output (`data/` folder). CSV files are written to `data/` under their normalized name. Whenever the written output is **not** a byte-for-byte, same-named copy of the input — a converted JSON file, a CSV that was re-serialised to be well-formed, or a CSV that was renamed to a compliant filename — the original is preserved untouched under `data/raw/`, and a top-level `.psychds-ignore` is written so the validator skips the raw copies. Only a clean CSV written verbatim under its own already-compliant name has no `data/raw/` copy.
+Every file ends up in `data/` as a CSV under a Psych-DS compliant name: JSON and JSON-Lines are converted, and CSV files are renamed if their name doesn't already fit the pattern.
 
-Files of any other type are ignored during metadata generation.
+Your originals are never modified. Whenever a file has to change on the way in, the untouched original is also saved under `data/raw/`. That covers three cases:
+
+- a JSON or JSON-Lines file converted to CSV;
+- a CSV rewritten because it wasn't strictly well-formed (for example, jsPsych stimulus HTML containing unescaped quotes);
+- a CSV renamed to fit the Psych-DS pattern.
+
+The one file with no copy under `data/raw/` is a well-formed CSV that already had a compliant name, since it's copied across unchanged. When `data/raw/` is used, the tool also writes a top-level `.psychds-ignore` so the validator doesn't check the originals.
+
+Files of any other type are ignored.
 
 ### Nested arrays and join keys
 
-When a data file contains nested arrays inside a trial, the tool extracts each array into its own Psych-DS CSV. Those rows need a column that uniquely identifies them. If `trial_index` alone isn't unique, the tool prompts (interactively) for additional **join-key** columns, grouping candidates into "Sufficient alone" and "Reduces duplicates", with a "Proceed anyway" escape. In a non-interactive run there is nothing to prompt, so the keys are resolved automatically and the choice is reported in the output. For JSON-Lines input with no per-trial identifier, a `source_record_id` (the source line) is synthesized so the join key can be formed; it marks the source record, not a real participant.
+When a trial holds a nested array, the tool extracts that array into its own Psych-DS CSV. Each extracted row needs a way to point back to the trial it came from — a **join key**: a column, or combination of columns, whose values differ for every row.
+
+`trial_index` is tried first. When it isn't enough on its own (most often in files where several participants were merged and `trial_index` restarts at 0 for each), the tool prompts for extra columns, sorted into "Sufficient alone" and "Reduces duplicates", with a "Proceed anyway" escape. In a run with no prompts, the keys are chosen automatically and the choice is reported in the output.
+
+JSON-Lines input sometimes has no per-trial identifier at all. In that case the tool adds a `source_record_id` column recording which line of the file each row came from, so a join key can be formed. It identifies the source record, not a participant.
 
 ### Folder depth
 
@@ -127,12 +139,12 @@ In **interactive mode**, the tool detects non-compliant names and offers a menu
 
 | Strategy | What it does | When offered |
 |----------|--------------|--------------|
-| **Use the value found inside each file** | Reads an ID column from the data (one unique value per file) and uses it as the value. The most reliable option, and recommended when available. | Only when such a column exists in *every* file. |
-| **Keep only the part that differs** | Strips the shared prefix/suffix across filenames; the varying middle becomes the value (you pick the keyword). | Only when the filenames share a common pattern. |
-| **Give the files fresh numbered names** | Replaces names with a clean sequence (`subject-001`, `subject-002`, …); you type the first name. | Always. |
-| **Keep the whole old filename as the value** | The fallback: the entire old name becomes one value under a keyword you pick. Nothing is lost, but names get verbose. | Always. |
+| **Use the value found inside each file** | Reads an ID column out of the data itself (one value per file) and uses that. The most reliable option — pick it when it's offered. | Only when such a column exists in *every* file. |
+| **Keep only the part that differs** | Drops whatever every filename has in common; the part that varies becomes the value, under a keyword you pick. | Only when the filenames share a common pattern. |
+| **Give the files fresh numbered names** | Replaces the names with a clean sequence (`subject-001`, `subject-002`, …); you type the first one. | Always. |
+| **Keep the whole old filename as the value** | The fallback: the entire old name becomes the value, under a keyword you pick. Nothing is lost, but the names get long. | Always. |
 
-After you pick a strategy, the tool shows the full set of proposed renames (including any sidecar CSVs from nested arrays, and auto-adjusting name collisions) and lets you **Apply**, **Edit one filename**, or **Choose a different strategy**. Psych-DS values may not contain hyphens or underscores, so those are stripped when a value is derived from a filename. For example:
+Once you pick a strategy, the tool shows every rename it proposes — including the companion CSVs from any nested arrays, with clashing names adjusted for you — and offers **Apply**, **Edit one filename**, or **Choose a different strategy**. Psych-DS values can't contain hyphens or underscores, so those are removed when a value comes from a filename. For example:
 
 ```
 participant_01.csv → subject-participant01_data.csv
@@ -155,7 +167,7 @@ Official Psych-DS keywords offered by the tool:
 | `site` | The site where data was collected |
 | `description` | A free-form label |
 
-Custom keywords are allowed but will produce a validator warning. In **non-interactive mode**, non-compliant filenames are a hard error — rename files before running.
+You may use a keyword outside this list — the dataset is still valid, but the validator will mention it. In a run with no prompts, a non-compliant filename is a hard error; rename those files before you run.
 
 ## Validation output
 
@@ -174,8 +186,8 @@ After generating `dataset_description.json`, the tool automatically validates th
   Error 1: JSON_KEY_REQUIRED: dataset_description.json is missing required field(s): [description]
 ```
 
-Warnings are advisory — they indicate recommended fields or practices that aren't strictly required. A dataset with warnings is still valid. Errors must be resolved for the dataset to be Psych-DS compliant.
+Warnings are advice: they point at recommended fields or practices you haven't followed. A dataset with warnings is still valid. Errors are different — the dataset isn't Psych-DS compliant until you fix them.
 
-Run with `--verbose` to see the full list of warnings alongside errors.
+Run with `--verbose` to see the full list of warnings alongside the errors.
 
-If validation fails due to missing required fields and you are running interactively, the tool will prompt you to fill them in before finishing.
+If validation fails because required fields are missing, an interactive run prompts you to fill them in before it finishes.

From 27b74514a0373430c0ac38f5f59a6ab48f2fdac0 Mon Sep 17 00:00:00 2001
From: Josh de Leeuw <josh.deleeuw@gmail.com>
Date: Sat, 25 Jul 2026 11:34:13 -0400
Subject: [PATCH 2/2] fix(frontend,website): repair a vacuous test assertion
 and widen the warnings note
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The upload-explainer toggle test asserted the collapsed state against
"Array values" — copy this branch had already replaced. The string was
absent whether or not the block collapsed, so the second half of the test
verified nothing. It now checks for the same text the open-state assertion
uses; confirmed load-bearing by forcing the block open, which fails it.

The warnings note dropped its zip/no-zip gating and now renders for any
warning list, including the bare-metadata save where MISSING_README_DOC is
genuine. "Recommended metadata you haven't filled in" is the wrong
description for that case — a missing README is a file, not an unfilled
field — so the note, and the two doc pages carrying the same sentence, say
"metadata or files".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/frontend/src/pages/Review.tsx       | 4 ++--
 packages/frontend/tests/ProjectInfo.test.tsx | 2 +-
 website/docs/guides/troubleshooting.md       | 2 +-
 website/docs/guides/using-the-wizard.mdx     | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/frontend/src/pages/Review.tsx b/packages/frontend/src/pages/Review.tsx
index 7aaa871..618b2fb 100644
--- a/packages/frontend/src/pages/Review.tsx
+++ b/packages/frontend/src/pages/Review.tsx
@@ -244,8 +244,8 @@ const Review: React.FC<ReviewProps> = ({ jsPsychMetadata, dataFiles, onDownloade
               <>
                 <p className={styles.issueGroupLabel}>Warnings</p>
                 <p className={styles.warnNote}>
-                  Warnings don't make a dataset invalid — they point at recommended metadata you
-                  haven't filled in.
+                  Warnings don't make a dataset invalid — they point at recommended metadata or
+                  files you haven't added yet.
                 </p>
                 <ul className={styles.issueList}>
                   {valResult.warnings.map((issue, i) => (
diff --git a/packages/frontend/tests/ProjectInfo.test.tsx b/packages/frontend/tests/ProjectInfo.test.tsx
index 60bdff9..e0bf311 100644
--- a/packages/frontend/tests/ProjectInfo.test.tsx
+++ b/packages/frontend/tests/ProjectInfo.test.tsx
@@ -236,7 +236,7 @@ describe("ProjectInfo", () => {
       expect(screen.getByText(/Lists \(e\.g\./)).toBeInTheDocument();
 
       await userEvent.click(btn);
-      expect(screen.queryByText(/Array values/)).not.toBeInTheDocument();
+      expect(screen.queryByText(/Lists \(e\.g\./)).not.toBeInTheDocument();
     });
   });
 
diff --git a/website/docs/guides/troubleshooting.md b/website/docs/guides/troubleshooting.md
index a7e618c..96b54a2 100644
--- a/website/docs/guides/troubleshooting.md
+++ b/website/docs/guides/troubleshooting.md
@@ -13,7 +13,7 @@ Common issues when generating metadata with the web wizard or the CLI, and how t
 **"Missing README" / "Missing CHANGES" warnings.**
 The wizard includes a placeholder `README.md` and `CHANGES.md` in the project you download, and validates them along with everything else, so these warnings shouldn't appear there. You will see them if you save only `dataset_description.json`, or if you validate a folder of your own that has no such files — add the two files to clear them.
 
-More generally: warnings never make validation fail. They flag recommended metadata you haven't provided, so they're worth reading, but a dataset with warnings is still valid.
+More generally: warnings never make validation fail. They flag recommended metadata or files you haven't added, so they're worth reading, but a dataset with warnings is still valid.
 
 **`JSON_KEY_REQUIRED: … missing required field(s)`.**
 Your `dataset_description.json` is missing a field Psych-DS requires — usually `description`. Fill it in on the wizard's Project info step, or, in the CLI, at the prompt that appears before it finishes. Then generate again.
diff --git a/website/docs/guides/using-the-wizard.mdx b/website/docs/guides/using-the-wizard.mdx
index 4a4aa68..b9558f4 100644
--- a/website/docs/guides/using-the-wizard.mdx
+++ b/website/docs/guides/using-the-wizard.mdx
@@ -97,7 +97,7 @@ Read through the generated `dataset_description.json`, go back to any step to ch
 
 **Errors** have to be fixed — the dataset isn't Psych-DS compliant until they are. Each one names the rule it broke and the files or columns at fault.
 
-**Warnings** never make validation fail. They point at recommended metadata you haven't filled in — an optional field, a suggested folder — so treat them as a checklist rather than a problem.
+**Warnings** never make validation fail. They point at recommended metadata or files you haven't added — an optional field, a missing `README.md` — so treat them as a checklist rather than a problem.
 
 The check covers exactly what you're about to download, `README.md` and `CHANGES.md` included, so there's no need to validate the project again afterwards.