# `submissions/`

Friends' benchmark contributions land here, one directory per submitter,
one subdirectory per device, one sub-subdirectory per run.

## Layout

```
submissions/
├── README.md                            — this file
├── EXAMPLE/                             — template; see below
│   └── mac-m1-8gb/
│       └── run-00000000-...-000000000000/
│           ├── manifest.json
│           ├── hardware.json
│           ├── run.jsonl
│           ├── metadata.json
│           └── run.md
├── alice/                               — first real friend's contributions
│   └── mac-m1-8gb/
│       └── run-<uuid>/...
└── bob/                                 — etc.
    └── rtx-4090-pc/
        └── run-<uuid>/...
```

## Per-submission contents

Five files inside each `run-<uuid>/`:

- **`manifest.json`** — automatic; `run_benchmark.py` writes it at run start. Contains submitter handle, device tag, target URL, model list, phase plan, canonical-options overrides, host hostname (short), platform, started-at timestamp.
- **`hardware.json`** — agent fills from a hardware probe (see `CLAUDE.md` §2). Schema version `hardware-1.0`.
- **`run.jsonl`** — automatic; the canonical event ledger. Line 1 is `type=meta`; subsequent lines are `type=call` or `type=skipped`; final line is `type=footer`.
- **`metadata.json`** — agent fills with computed aggregates per `(cell_id, phase)` cell. Schema version `metadata-1.0`. The catalogue builder will recompute on Sloba's side; having it in the PR makes review fast.
- **`run.md`** — agent fills using the `CLAUDE.md` §6b template. Honest narrative — methodology deviations, caveats, headline numbers.

## Why per-submitter folders?

- **Attribution** — your handle lives next to your data
- **Reviewability** — a PR adds files only under `submissions/<your-handle>/...`; reviewer can see the whole contribution at a glance
- **No collisions** — two friends submitting from "macbook-pro" don't overwrite each other
- **History stays clean** — re-runs go into new `run-<uuid>/` subdirs, not on top of the old one

## Naming conventions

- **`<submitter-handle>`** — your Gitea username, or any other handle you'd like to be credited as. Lowercase; ASCII letters / digits / hyphens only.
- **`<device-tag>`** — short descriptor of the hardware. Pattern: `<chip-or-platform>-<key-spec>`. Examples:
    - `mac-m1-8gb`, `mac-m2-pro-16gb`, `mac-m3-max-64gb`
    - `rtx-4090-pc`, `rtx-3060-laptop`, `gtx-1060-6gb`
    - `ryzen-7950x-cpu`, `intel-i9-13900k-cpu`
    - `pixel-8-pro`, `samsung-s24-ultra` (yes, phones — if you've got termux working)
    - `runpod-h100-pcie`, `runpod-rtx-a6000`
- **`run-<uuid>`** — `run-` prefix + a UUID v4 from `run_benchmark.py`. Don't shorten.

## What the EXAMPLE folder is for

A complete-but-tiny submission you can read end-to-end to understand the
shapes. **Don't modify the EXAMPLE folder in a benchmark-submission PR**; if
you spot a bug in the example, that's a separate PR with the title
`fix: submissions/EXAMPLE/...`.

## When a submission is merged

Sloba reviews and merges manually. After merge:
1. The catalogue builder on Sloba's side picks up your run, computes a
   `cell_id` from your `device-tag` + model, and assigns it a `site_grade`
   (flagship / standard / archive-only based on the criteria in
   `methodology.md`).
2. Janie (the benchmarks blogger) may write a `janie_blurb_md` for it.
3. It appears on `benchmarks.weeyuga.com` (when the site is live).
4. Your `device-tag` becomes a permanent comparison axis on the catalogue.

## What if I want to delete a submission later?

Open an issue, we'll honor the request promptly. We'll keep the run
directory but mark it `visibility: redacted` in the catalogue overlay so
the data still validates historical analysis claims while disappearing
from the browse surface.