Project Folder Reference

A valid Project is a visible folder with a valid knotest.json manifest. Files under known paths are Project truth or owned content. Files under .knotest/ are disposable indexes, locks, scratch data, and caches.

Format 5 layout

<Project>/
  knotest.json
  materials/
    tags.json
    datasets/<slug>/...
    datasets/<slug>.material.json
    dataset-revisions/<dataset-id>/<revision>.json
    models/<material-id>.<ext>
    models/<model-id>.model.json
  api-profiles/<api-profile-id>.api-profile.json
  dossiers/<dataset-slug>.dossier.json
  risks/register.json
  attachments/<uuid>-<filename>
  proposals/<name>.json
  presets/<id>.preset.json
  project-profile.json
  evaluation-metadata/<evaluation-id>.json
  prediction-sets/<prediction-set-id>.json
  prediction-set-metadata/<prediction-set-id>.json
  reports/<evaluation-id>/<report-draft-id>.json
  claims/<date>-evaluation-<evaluation-id>.claim.json
  evidence/<claim-shortid>/...
  .knotest/
    lock
    index.sqlite
    run-scratch/
    cache/

Files outside known paths are ignored. Knotest does not delete or rewrite an unknown file merely because it is inside the Project.

Project manifest

knotest.json identifies the Project and format:

{
  "created_at": "2026-07-20T00:00:00Z",
  "format_version": 5,
  "name": "Fraud detector audit",
  "project_id": "72d4ccdb-0fa8-4a09-970d-78586e464d82"
}

Knotest rejects an unsupported format version. A malformed known file below a valid manifest degrades Project health; it does not make the folder cease to be a Project.

Ownership and publication

Each command publishes its owner file only after the owned bytes are prepared. For an Evaluation, Evidence is published first and the Claim is the immutable commit marker. Prediction Generation follows the same order with the Prediction Set owner. Interrupted work can therefore leave unreferenced bytes, but those bytes are not Project truth.

Mutable presentation owners, such as an Evaluation display name or report draft, do not rewrite sealed Claims or Evidence.

Path requirements

Paths stored in Project truth are relative to the Project root, use / separators, remain beneath the root, and cannot cross links or path indirection. Absolute paths are used only when selecting a Project root or a new import source; they are not written into Claims or Evidence.

Working with the folder

• Close the Project before editing known owner files outside Knotest.
• Back up the entire visible Project folder.
• Do not rely on .knotest/ when transferring or restoring a Project.
• Do not modify Claim, Prediction Set, or Evidence files in place.
• After restoring or moving a Project, open it in Knotest and check its records.
• Keep credentials and application settings out of the Project.