VEHICLE LAB / DOCUMENTATION

Project reference

A project is a JSON manifest plus local assets. The CLI validator is the executable reference for version 1; project.schema.json is the machine-readable structural reference.

{
  "schemaVersion": 1,
  "id": "my-rover",
  "name": "My rover",
  "description": "Compare two suspension packages.",
  "units": "mm",
  "models": [{
    "id": "rover",
    "metadata": "projects/my-rover/assets/rover.json"
  }],
  "stages": [{
    "id": "inspect", "title": "Inspect the front linkage",
    "description": "Check the mounting interfaces.",
    "model": "rover", "status": "unverified"
  }],
  "revisions": [{
    "id": "R0", "parents": [],
    "decision": "First packaging experiment."
  }],
  "evidence": [],
  "claims": {"physicalValidation": false, "hardwareRelease": false}
}

Fields and invariants

Field	Contract
id	Lowercase letters, digits and hyphens; at most 64 characters.
models	Unique model IDs with metadata paths relative to the source directory.
stages	One to eight stages; each has a title, description and exactly one existing model or replay reference.
revisions	Unique revision IDs; parents must exist; cycles are rejected. A decision records why a revision exists.
evidence	Local path, SHA-256, kind, scope and an observed, failed or unverified status.
claims	Both physicalValidation and hardwareRelease are false in this experimental release.

Portable asset paths

Create notebooks under projects/<id>. Other initialization locations are rejected before any files are written.

Use relative paths made of letters, digits, underscores, hyphens and dots, separated by single forward slashes. Nested assets such as projects/my-rover/assets/cad/frame.json are supported. Segments must not begin with a dot. Parent traversal, hidden paths, escaping symlinks, remote URLs, URL escapes and missing files are rejected. Metadata paths are relative to the source directory; binary paths are relative to their metadata file. The browser opens manifests under projects/<id>/project.json.

Revision decisions

Keep a revision when it changes a meaningful design decision. Explain the hypothesis, result and next question. Media exports and software checks may be evidence records; they are not equivalent to physical prototypes. The bundled vehicle register preserves the original branch identities and parent links.

Open Project record in your notebook to inspect parent links and decisions. Evidence can name an existing revision through its optional revision field. Every artifact is hash-verified before display; small text and JSON records can be read inline and all original bytes can be downloaded. Model stages show their exact observed, failed or unverified status. These outcomes remain separate from the whole project's physical-validation flags.

Versioning

Version 1 is an initial interface. An incompatible geometry, unit or replay change must use a new schema version and a migration path. Preserve old evidence bytes if their results are still cited.