docs(website,frontend): rewrite docs and wizard copy for researchers

[jodeleeuw]

Rewrites the six documentation pages and the wizard's interface text for readers who run jsPsych experiments but are not developers. Two factual bugs surfaced during the pass and are fixed here too.

Copy

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 needed and linked to from the rest.

In the wizard: labels match what the docs call them, field hints drop the SPDX/canonical-URL jargon, @type becomes Author type and Privacy policy becomes Sharing restrictions (both still naming the underlying JSON key so the preview stays readable), and errors say what to do next instead of dumping exception text into the file list. The processing summary reports outcomes — Finished. 3 files read, 1 skipped. — rather than counting skipped and failed files as "processed". Destructive confirmations now state that files on disk are untouched.

One doc fix worth calling out: the wizard guide claimed variables with unknown descriptions "appear expanded at the top". They start collapsed, under a Missing descriptions heading.

Validation now checks what you actually download

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 against documents the download does contain, and Review carried a note explaining the false alarm away.

Both Psych-DS rules are presence-only (stem + extensions at the dataset root, no content requirements), so handing the validator the same bytes the zip carries is an honest check rather than a suppression. Verified against psychds-validator directly rather than inferred from the schema:

	warnings	README/CHANGES
without the two files	8	both fire
with the exact bytes the zip writes	6	both gone

Their content now lives once in datasetLayout.ts, shared with the zip builder so the two can't drift — that module's header already said it exists so the download and the validator "never drift", which is precisely the drift that caused this.

The project name is passed only when a zip is on offer. Saving the bare dataset_description.json produces no such files, so those warnings are real advice about the user's own folder and still appear. Two tests cover both directions.

A command that never existed

Review pointed at npx @jspsych/cli validate — a package that is not on npm, with a subcommand the metadata CLI never had (it defines yargs .option()s only, so a bare validate positional is silently ignored). The --psych-ds-dir flag in the second line suggests this repo's CLI was meant, but no invocation of it validates a folder: it always wants a data directory and rewrites dataset_description.json as it goes.

Since validation now covers the whole downloaded project, the re-validation block was removed rather than corrected, along with its dead styles. The stale reference is also gone from packages/frontend/README.md, docs/dev/frontend-architecture.md, and a source comment.

Notes for review

• Rebased onto current main. docs(website): rewrite CLI guide as prompt-by-prompt walkthrough #143 rewrote using-the-cli.mdx while this was in flight; its prompt-by-prompt structure wins every conflict, and its dedicated join-key step made my paragraph there redundant. The raw/ tree comment is corrected — main's "if inputs were JSON/JSON-Lines" misses renamed and rewritten CSVs.
• Six frontend files were touched by both Align the wizard with the docs theme; stepper sidebar #144 and this branch and auto-merged without conflict; each was diffed against origin/main to confirm nothing was dropped.
• 269/269 frontend tests, tsc clean, site builds. Test churn is assertion updates tracking the new copy, plus two new validation tests.
• Not included: the postcss/undici overrides in the working tree. Related: the lock file currently has postcss removed but not reinstalled, so npm run build in website/ fails before Docusaurus starts and the wizard bundle in website/static/wizard-app/ is stale — the in-app copy here won't show on the site until that's resolved and the wizard is rebuilt.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 27b7451

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
frontend	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jodeleeuw]

Pushed 27b7451 with fixes for the two review findings.

• ProjectInfo.test.tsx — vacuous assertion. "pre-fill help button toggles the upload explainer" had its open-state assertion migrated to the new copy, but the collapse assertion still looked for Array values, which this branch deleted. That string was absent whether or not the block collapsed, so the second half of the test verified nothing. It now checks the same text the open assertion uses. Confirmed load-bearing by forcing the block permanently open — the test fails as it should, then passes again once reverted.
• Warnings note wording. The note lost its zip/no-zip gating and now renders for any warning list, including the bare-metadata save where MISSING_README_DOC is genuine — and "recommended metadata you haven't filled in" is the wrong description there, since a missing README is a file, not an unfilled field. Now reads "recommended metadata or files you haven't added yet". Applied the same correction to the two doc pages carrying that sentence (troubleshooting.md, using-the-wizard.mdx).

269/269 tests pass, tsc clean.

One cross-PR note, also left on #145: this branch conflicts with #145 in Review.module.css (verified with git merge-tree — both are MERGEABLE against main individually, but not with each other). #145 appends a phone block after .cliAltSummary:hover, which this branch deletes, and its .cliBlock { overflow-x: auto } rule targets a class this branch removes. Landing this one first is the cleaner order — #145 then just drops one orphaned rule on rebase. Whichever way, the conflict shouldn't be resolved by keeping both sides.

Separately, the stale website/static/wizard-app/ bundle you flagged is still a real gap: troubleshooting.md now asserts the README/CHANGES warnings "shouldn't appear" in the wizard, which is only true once the rebuilt bundle ships. The docs deploy independently of it. I hit the same blocker locally — postcss is missing from node_modules, so npm run build fails before Vite starts.