Add Psych-DS metadata + DataPipe docs under Learn

docs/docs/extend/extensions/extension-development.md

@@ -171,7 +171,7 @@ MyAwesomeExtension.info = {
 }
 ```
 
-The `version` field describes the version of the extension used and then durin the experiment will be part of the generated data. This is used generate metadata and help maintain the Psych-DS standard. It should imported from the package.json file by including an import statement in the top of the index.ts file. This allows the `version` field be automatically updated with each changeset. If you are not using a build environment and instead writing a plain JS file, you can manually enter the `version` as a string as done in the comment.
+The `version` field describes the version of the extension used, and during the experiment it becomes part of the generated data. This is used to generate metadata and help maintain the [Psych-DS standard](../../learn/guides/metadata-what-is-psych-ds.md). It should be imported from the package.json file by including an import statement at the top of the index.ts file. This allows the `version` field be automatically updated with each changeset. If you are not using a build environment and instead writing a plain JS file, you can manually enter the `version` as a string as done in the comment.
 
 The `data` field is an object containing all of the `data` generated for the plugin. Each 'data' object has a `type` and `default` property. Additionally, this should be only used for data you choose to generate. Any jsdoc (comments included in the /** */ tags) you include will be scraped as metadata if you are choosing to generate metadata. This scraped metadata will also be used to create the JsPsych documentation.
 

docs/docs/extend/plugins/plugin-components.md

@@ -116,7 +116,7 @@ If the `default` value is `undefined` then a user must specify a value for this
 
 jsPsych allows most [plugin parameters to be dynamic](../../learn/concepts/dynamic-parameters.md), which means that the parameter value can be a function that will be evaluated right before the trial starts. However, if you want your plugin to have a parameter that is a function that _shouldn't_ be evaluated before the trial starts, then you should make sure that the parameter type is `'FUNCTION'`. This tells jsPsych not to evaluate the function as it normally does for dynamic parameters. See the `canvas-*` plugins for examples.
 
-We strongly encourage using [JSDoc comments](https://jsdoc.app/about-getting-started) to document the parameters and data generated by the plugin, as shown below. We use these comments to automatically generate documentation for the plugins and to generate default descriptions of variables for experiment metadata.
+We strongly encourage using [JSDoc comments](https://jsdoc.app/about-getting-started) to document the parameters and data generated by the plugin, as shown below. We use these comments to automatically generate documentation for the plugins and to generate default descriptions of variables for [experiment metadata](../../learn/guides/metadata-what-is-psych-ds.md).
 
 ```js
 const info = {

docs/docs/learn/deploy/running-experiments.md

@@ -90,6 +90,7 @@ To be maximally flexible, jsPsych doesn't provide a single built-in solution for
 Some options for running your jsPsych experiment online include:
 
 * [Cognition.run](https://www.cognition.run/) - A free service designed specifically for hosting jsPsych experiments, with an easy-to-use interface. 
+* [DataPipe](../guides/datapipe.md) - A free, jsPsych-maintained service that saves data to the [Open Science Framework](https://osf.io/) without you running a server or database. It handles the data-saving side rather than hosting the experiment files, so it pairs with a static host such as GitHub Pages.
 * [JATOS](https://www.jatos.org/Whats-JATOS.html) - A free program that runs on your own server and provides a GUI for setting up experiments and accessing the data. Offers lots of features for creating more complex experiments and managing multiple researchers.
 * [Pavlovia](https://pavlovia.org/) - A paid hosting service for web-based experiments, run by the PsychoPy team. Experiment files are managed on a GitLab repository. Participants will access the experiment through a link to Pavlovia.
 * [PsiTurk](https://psiturk.org/) - Python-based program to help you host your experiment on your own computer and collect data from MTurk (see Recruiting Participants below). Relatively easy for a DIY option.

docs/docs/learn/guides/datapipe.md

@@ -0,0 +1,130 @@
+---
+title: DataPipe
+description: Born-open data collection — send jsPsych data straight to an OSF project, with automatic Psych-DS metadata.
+tags:
+- Data
+- Method
+---
+
+# DataPipe
+
+[DataPipe](https://pipe.jspsych.org) is a **free, open-source service** that sends data from any online experiment directly to the [Open Science Framework](https://osf.io) (OSF). No server setup, no download step. DataPipe is built by the [jsPsych](https://www.jspsych.org) team.
+
+:::tip Full documentation
+
+This page covers the essentials of using DataPipe with jsPsych. To use DataPipe itself, or to read the complete, always-current documentation — including the full API and FAQ — go to **[pipe.jspsych.org](https://pipe.jspsych.org)**.
+
+:::
+
+## How it works
+
+Three steps to start collecting data:
+
+1. **Create an OSF project** and link your OSF account to DataPipe.
+2. **Set up an experiment on DataPipe** and add a few lines of code to your study to send data through the API.
+3. **Activate data collection.** Participant data goes straight to your OSF project as files — no downloads, no manual transfers.
+
+Using jsPsych? One trial saves all your data:
+
+```javascript title="experiment.html"
+// Save data with the jsPsych pipe plugin
+const save_data = {
+  type: jsPsychPipe,
+  action: "save",
+  experiment_id: "your_id",
+  filename: filename,
+  data_string: () => jsPsych.data.get().csv()
+};
+```
+
+Not using jsPsych? A single fetch call is all you need:
+
+```javascript title="experiment.js"
+// Send data with a fetch request
+fetch(url, {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({
+    experimentID: "your_id",
+    filename: "subject01.csv",
+    data: dataAsString
+  })
+});
+```
+
+## Getting started
+
+Set up DataPipe to send experiment data directly to the OSF using free tools.
+
+1. **Create an OSF project.** Make a project at [osf.io](https://osf.io) to store your data (you'll need a free OSF account). Your OSF account can also sign you in to DataPipe directly.
+2. **Link your OSF account to DataPipe.** DataPipe needs authorization to create files in your OSF projects. If you sign in with your OSF account this is automatic; otherwise, use **Link OSF Account** in your [Account Settings](https://pipe.jspsych.org/admin/account). (A legacy personal-access-token option is also available — see [pipe.jspsych.org](https://pipe.jspsych.org).)
+3. **Create a DataPipe experiment.** Click **New Experiment** and provide a title, your **OSF Project ID** (the short code from the project URL, e.g. `abcde` in *osf.io/abcde*), and a **Data Component Name** for the component DataPipe creates to hold your data files.
+4. **Configure the experiment.** The dashboard has optional features: condition assignment, data validation (with required-field checks), a session limit, and Psych-DS metadata. See [Metadata with DataPipe](#metadata-with-datapipe) below.
+5. **Add code to your experiment.** With jsPsych, the easiest option is the [jsPsychPipe plugin](https://github.com/jspsych/jspsych-contrib/tree/main/packages/plugin-pipe); otherwise call the [API](#sending-data) directly. Ready-to-use snippets for both are on your experiment dashboard.
+6. **Publish your experiment online.** Host it on any web server — university hosting, GitHub Pages, Netlify, etc.
+7. **Activate and test.** Turn on the features you need (data collection, base64 collection, condition assignment, Psych-DS metadata), then run through your experiment once to confirm files appear in your OSF component.
+
+:::warning
+
+Only activate the features you need, and only during active data collection. DataPipe creates an open path to your OSF project — validation and session limits reduce the risk of unwanted submissions.
+
+:::
+
+<details>
+<summary>Publishing with GitHub Pages (a free option)</summary>
+
+1. Create a GitHub account and a [new repository](https://www.github.com/new). The repo name becomes part of your experiment URL, so avoid names that reveal information to participants. Add a README so the repo isn't empty.
+2. Go to **Settings → Pages**, set the source to **Deploy from a branch**, select **main**, and click **Save**.
+3. Use **Add Files → Upload Files** to upload your experiment, then **Commit Changes**.
+
+Your experiment will be at `https://[username].github.io/[repo-name]`. If your HTML file isn't named `index.html`, append its filename. It can take a few minutes to go live.
+
+</details>
+
+## Sending data
+
+All endpoints accept JSON request bodies with `Content-Type: application/json`, and need the **experiment ID** from your dashboard. Your dashboard also shows ready-made code samples.
+
+- **Save text data** — `POST https://pipe.jspsych.org/api/data/`. Send `experimentID`, a unique `filename` (e.g. `subject01.csv`), and `data` (the file contents as a string). Validation rules, if configured, run before the file reaches OSF.
+- **Save base64 data** — `POST https://pipe.jspsych.org/api/base64/`. Same fields, with `data` as a base64-encoded string; DataPipe decodes it and stores the binary file (audio, video, images).
+- **Get condition assignment** — `POST https://pipe.jspsych.org/api/condition/`. Send `experimentID`; returns the next condition number, cycling `0 … n−1` for balanced assignment.
+
+A successful request returns `{ "message": "Success" }` (the condition endpoint also returns a `condition`). On failure the response has an `error` code and a `message` — common ones include `MISSING_PARAMETER`, `EXPERIMENT_NOT_FOUND`, `DATA_COLLECTION_NOT_ACTIVE`, `SESSION_LIMIT_REACHED`, `INVALID_DATA`, and `OSF_FILE_EXISTS`. See the [full API reference](https://pipe.jspsych.org/api-docs) for every field and error code.
+
+## Metadata with DataPipe
+
+DataPipe can automatically generate machine-readable metadata describing your dataset according to the [Psych-DS specification](https://psychds-docs.readthedocs.io/en/latest/) — a community standard that makes datasets easier to understand, share, and reuse. For background on the standard and the standalone tools, see [What is Psych-DS?](./metadata-what-is-psych-ds.md)
+
+When enabled, DataPipe writes a `dataset_description.json` to your OSF project and updates it as new sessions arrive. For each variable it records the data type and, when available, a human-readable description drawn from the relevant jsPsych plugin documentation, plus observed numeric ranges and categorical values across sessions.
+
+:::warning Generated, not validated
+
+DataPipe **generates** these files from your incoming data using the [@jspsych/metadata](https://github.com/jspsych/metadata) library — the same code the [metadata CLI](./metadata-cli-guide.md) uses. It does **not** run a Psych-DS validator on the result. To confirm a dataset passes validation, run the [Psych-DS validator](https://psych-ds.github.io/validator/) on the files in your OSF project separately.
+
+:::
+
+With metadata enabled, each submission produces a Psych-DS-compliant layout in your OSF data component:
+
+- `dataset_description.json` — the dataset-level metadata file, updated after every session.
+- `data/raw/<original filename>` — your original submission, stored byte-for-byte. This is the critical upload; every other file is derived from it.
+- `data/<name>_data.csv` — the main data table as CSV (CSV submissions keep their exact bytes; JSON is converted to a CSV table).
+- `data/<name>_measure-<column>_data.csv` — one sidecar CSV per column that holds nested arrays-of-objects or objects, so nested measures stay analyzable as flat tables.
+- `.psychds-ignore` — placed at the component root so validators skip the `data/raw/` folder.
+
+Metadata production is **strongly recommended** when you plan to share or publish your data. To enrich the generated metadata — authors, a study description, custom variable descriptions — the [metadata options format](./metadata-options.md) and [CLI](./metadata-cli-guide.md) work on the same `dataset_description.json` files.
+
+## Good to know
+
+- **DataPipe is free.** The costly parts of online studies — hosting and storage — are handled by free services (GitHub Pages, the OSF); DataPipe is a lightweight bridge between them.
+- **DataPipe doesn't store your data.** It routes data to your OSF project and keeps no copy. The one exception: if an OSF upload fails, the data is cached (encrypted, up to one week) and retried automatically until it succeeds.
+- **DataPipe won't host your experiment.** You need separate hosting (GitHub Pages, Netlify, university servers). DataPipe only sends data to OSF.
+- **There's a 32 MB request limit,** enforced by the server. Most jsPsych datasets are far smaller (≈50 KB–5 MB); the pipe plugin gzip-compresses text data, effectively raising the limit for most experiments.
+- **Who can see your data** depends on your OSF settings — a private component is visible only to you and your collaborators.
+
+For the complete FAQ (security, one-click auth, condition designs, and more), see [pipe.jspsych.org](https://pipe.jspsych.org).
+
+### How to cite DataPipe
+
+If you use DataPipe to collect data, please cite:
+
+> de Leeuw, J. R. (2024). DataPipe: Born-open data collection for online experiments. *Behavior Research Methods*, 56(3), 2499–2506. [https://doi.org/10.3758/s13428-023-02161-x](https://doi.org/10.3758/s13428-023-02161-x)