Prepare a dataset contribution

Start with one representative capture and its supporting files. You do not need a complete archive, an anomaly assessment or every metadata field to begin. Keep missing information explicit so the next person knows what still needs to be established.

This guide creates a source intake receipt: a local inventory of received files, their fingerprints and the information still needed to use them. It does not upload files or publish a dataset.

You need Node.js 22 and npm for the exercise. It uses the published CLI 2.0.0-beta.4 and the existing fictional DisclosureOS example case. No source checkout is required.

Receive one file

Create a working folder and install the CLI:

mkdir dataset-contribution
cd dataset-contribution
npm init -y
npm install --save-dev @disclosureos/cli@2.0.0-beta.4

Download the example optical readings and save the file as optical.csv in this folder. Keep the downloaded bytes unchanged; opening and saving the CSV in a spreadsheet can change them. These are fictional readings, not partner data.

Receive the file, then check the saved receipt and its copy:

npx disclosureos intake create optical.csv --out intake-01 --json
npx disclosureos intake validate intake-01/intake.json --json

The CLI leaves optical.csv intact and creates:

dataset-contribution/
  optical.csv              Original downloaded file
  intake-01/
    intake.json            Receipt and missing context
    files/
      file-1               Exact copy of optical.csv

The receipt retains originalName: "optical.csv", its SHA-256 fingerprint and its byte length. File IDs belong to this receipt; file-1 in another receipt can identify a different file. The receipt's ID and receivedAt value change each time. Receipt time is not capture time.

To receive several files, list each local path before --out. The output directory must not already exist. To repeat the exercise, choose a new name such as intake-02. The CLI does not overwrite an existing receipt.

Read the check result

The validation command exits with status 0. Its JSON includes these fields; this is a shortened view of the result:

{
  "success": true,
  "researchEligibility": "not_checked",
  "validation": {
    "success": true,
    "files": [{ "id": "file-1", "status": "passed" }],
    "artifactContents": "not_checked",
    "authorization": "not_checked"
  }
}

validation.files confirms that the saved copy matches the receipt's length and fingerprint. It does not establish that the measurements are correct, the named source is authentic or publication is permitted.

The result also lists nine gaps: publisher, license, access, file role, format, instrument, calibration, clock and acquisition time. These are expected. Intake does not decode the CSV, infer its format from the extension or read timestamps into the receipt. Even information available in the example case stays unknown until it is supplied explicitly.

Each entry in validation.gaps gives a location, reason and next action. Missing context can coexist with a passing file-identity check. Use those gaps as a handoff checklist, not as permission to invent values.

node -e "require('node:fs').appendFileSync('intake-01/files/file-1', '\n')"
npx disclosureos intake validate intake-01/intake.json --json

node -e "require('node:fs').copyFileSync('optical.csv', 'intake-01/files/file-1')"
npx disclosureos intake validate intake-01/intake.json --json

npx disclosureos intake inspect intake-01/intake.json --json reads the receipt without opening its source files. Its fileIdentity: "not_checked" is intentional. Use npx disclosureos intake validate with the receipt path when you need a file check. CLI exit status 2 means a usage or file-operation error; inspect the returned issues before retrying.

Choose a useful first slice

For your own data, select a capture whose format and collection context someone can explain. Include background or known-control periods when available, alongside any interval the provider has identified for investigation. State how the slice was chosen and what was left out.

Keep native files alongside exports and derived products. A convenient JSON export may combine readings, calculated values and provider interpretations; it is not automatically raw data. Preserve separate device identities, clocks and sessions even when files appear together in one folder.

The intake CLI accepts local regular files, with a maximum of 4,096 files, 256 MiB of combined source bytes and an 8 MiB receipt. It does not import an entire archive, fetch URLs or decode proprietary formats. For a larger archive, agree on a bounded first exchange and retain an inventory of the remainder. Do not truncate files silently to fit the limit.

What to provide

Send supporting notes with the files. An explicit “unknown” with a reason is more useful than a guessed value or an empty cell.

Receipt declarations are deliberately small. Keep detailed configuration, calibration and processing documents as additional source files, then connect them through the relevant standard documents during integration. Preserve the original receipt if you revise its declarations, and keep the original source bytes unchanged.

Prepare the handoff

Keep intake.json and its files/ directory together. Add a short README that explains the exchange. This outline is a human-readable cover note, not another required schema:

Provider and contact:
Purpose and selection of this slice:
Capture or session boundaries:
Files supplied and their roles:
Device/channel mapping:
Timing, units and reference frames:
Calibration and processing documents:
Known gaps and who can clarify them:
Permitted uses and required attribution:
Remaining archive and proposed next exchange:

Include the CLI version and saved validation result. The CLI reports the receipt's fingerprint as manifestSha256; keep it in a separately retained handoff record so a recipient can check that the manifest itself has not changed. File hashes inside a manifest do not authenticate that manifest or its publisher.

Coordinate the scope and transfer method with maintainers through the project repository. Start with a description of the proposed contribution. Agree on where files should go and their sharing terms before transferring them; do not attach restricted source data to a public issue. This portal does not provide an upload or publication service.

Connect the files to the standard

Intake is the starting point. Choose the next step according to what you can establish from the source:

Reproduction packets and dataset releases are later, separate checks. The published packet commands check pinned inputs and research prerequisites. The dataset commands check a release composed of those packets and their nominal session membership. This release profile requires qualifying packets; it is not the intake gate for unassessed files. Receive the source files first; add reviews when there is a documented assessment to record.

inspect reads a manifest; validate checks its supplied files and the applicable profile. packet reproduce supports only the CLI's bundled demonstration method, not arbitrary contributor code. None of these commands establishes scientific validity or permission to publish. See the intake contract, packet reference and dataset release reference at the published beta's source revision. The source links specify the contract fields and profile checks; the walkthrough above uses the installed CLI.

ELDÆON preview

The public mission viewer uses native files supplied by ELDÆON: environmental and muon logs, processed passive-radar exports, video and an EEG recording. The import is incomplete. Sensor windows retain file identifiers and source rows; videos and EEG use relative playback until their absolute clock alignment is established. The source library lists received and missing files, known defects and a source-intake receipt. The preview is not a scientific assessment or a canonical dataset release.

Further integration depends on confirmed device/channel meanings, clock alignment and calibration context. The received-file inventory and import checks do not fill those gaps. The fictional example used in this guide demonstrates the intake process separately from the real mission.

For a quick browser check of supported Observation or claim-history documents, use the local inspector. It does not validate an intake receipt, import a native dataset or publish it.

For a bounded real-data implementation, reproduce an ELDÆON reading. It connects one retained source row to the published standard and reports the missing capture context separately.