# Repository layout

Paths identify artifact type, model family, and a coherent release or method group.
The catalog records tasks and modalities; folders do not impose a t2v/i2v pipeline.
This supports diffusion and non-diffusion approaches, image and video methods, full models,
adapters, face replacement, reenactment, avatar pipelines, and future artifact types.

```text
models/<family>/<group>/<artifact-type>/
workflows/<runtime>/<family>/<group>/
scripts/<family>/<group>/
integrations/<runtime>/
reports/<family>/<group>/
experiments/<study>/
manifests/artifacts.json
docs/
licenses/
```

| Path | Contents |
| --- | --- |
| `models/` | Weights, model cards, licenses, and notices. Artifact types can be `loras`, `checkpoints`, `encoders`, `vaes`, `onnx`, or another descriptive directory. |
| `workflows/` | Runnable workflows organized by runtime. Store GUI JSON at the group root and API JSON in `api/`. Other runtimes use their own directories. |
| `scripts/` | Extraction, conversion, training, inference, and evaluation scripts with explicit arguments and a usage document. |
| `integrations/` | Runtime-specific loaders, nodes, or plugins shared by compatible workflows. |
| `reports/` | Numerical extraction and validation results, without test media or execution-history dumps. |
| `experiments/` | Completed studies: reports, configurations, numerical results, runtime evidence, source/published SHA provenance, model URLs and reproducibility instructions. Exclude media, weights, embeddings and raw histories. |
| `manifests/` | Machine-readable artifact inventory and compatibility information. |
| `docs/` | Collection-wide conventions and instructions. |
| `licenses/` | Shared license texts; model-specific licenses also accompany model groups. |

## Adding artifacts

1. Choose lowercase kebab-case family and group names, such as `minimax-h3/viggle-delta`.
2. Add weights under their artifact type. Include a group README, license, provenance, and notices.
3. Place companion workflows, scripts, integrations, and reports under their corresponding roots.
4. Add one catalog entry per independently selectable model variant. Record paths, roles, bytes,
   SHA-256, kind, tasks, modalities, exact base compatibility, dependencies, license, and validation.
5. Use generic media placeholders. Exclude private media, output previews, histories, credentials,
   cache files, and machine-specific filesystem paths from the public release.

Do not create empty directories for hypothetical future families. Add a family when its first
artifact is ready. Published filenames should remain stable; distinguish new versions explicitly
when compatibility changes. Existing upstream filenames may retain underscores for loader compatibility.

## Catalog

`manifests/artifacts.json` uses `schema_version: 1` and an `artifacts` array.
Every entry has a stable `id`, `family`, `group`, `kind`, `tasks`, `modalities`, and `files`.
Model-specific fields, such as `rank`, `base_model`, or `precision`, are optional for other kinds.
Each file record includes its repository-relative path, role, byte size, and SHA-256.
Workflow references identify their runtime and format. Compatibility constraints belong to the
artifact entry and group documentation, rather than being inferred from a shared repository tag.