Add the model card standard

Every model repository's README follows one shape: four sections generated
from the tree and the config.json files, plus hand-written free sections for
what the artifacts cannot express. Records which facts a card must not
restate, so a card and the files it describes cannot disagree.

MODEL_CARD.md

@@ -0,0 +1,167 @@
+# Model card standard
+
+Every `software-mansion/react-native-executorch-*` repository carries a
+`README.md` in this shape. Four sections are **generated** from the repository
+tree and its `config.json` files, so they cannot drift from what is published.
+Anything a model needs beyond them is a **free section**, written by hand and
+kept as-is.
+
+Before this standard the estate had 12 distinct heading sequences, four
+heading-level conventions, and five different ExecuTorch versions claimed in
+prose while 28 of 54 cards claimed none.
+
+## Front matter
+
+Hugging Face card metadata. Required on every repository:
+
+| key | value |
+| --- | --- |
+| `license` | An SPDX-style Hub identifier for the **upstream** license, not ours. Use `other` plus `license_name` and `license_link` when the upstream license has no Hub identifier. |
+| `pipeline_tag` | The Hub task this model serves, so it appears in task search. |
+| `library_name` | Always `executorch`. |
+
+Optional: `base_model`, `language`, `tags`. Keep the same identifier here and in
+the `license` field of every `config.json` in the repository; they are checked
+against each other.
+
+## Generated sections
+
+### 1. Title and introduction
+
+The `# ` title is the repository slug with the `react-native-executorch-`
+prefix dropped. One paragraph naming the library, then the upstream model on
+its own line:
+
+```markdown
+# <slug>
+
+This repository hosts the **<slug>** models exported for the
+[React Native ExecuTorch](https://www.npmjs.com/package/react-native-executorch)
+library as ExecuTorch `.pte` programs, ready to run on device.
+
+Upstream model: [<name>](<url>)
+```
+
+Omit the upstream line when there is no single upstream to point at, rather
+than guessing a URL.
+
+### 2. Variants
+
+One row per published `.pte`, read from the `variants` array of every
+`config.json`.
+
+```markdown
+## Variants
+
+| Path | Backend | Precision |
+| --- | --- | --- |
+| `xnnpack/model_xnnpack_fp32.pte` | xnnpack | fp32 |
+| `xnnpack/model_xnnpack_int8.pte` | xnnpack | int8 |
+| `coreml/model_coreml_fp16.pte` | coreml | fp16 |
+```
+
+A variant that ships several `.pte` files declares them as a `components` map
+of role to filename, and contributes one row per component. Those repositories
+gain a `Component` column naming the role; repositories without components do
+not carry the column, so the common case stays three columns wide.
+
+```markdown
+| Path | Component | Backend | Precision |
+| --- | --- | --- | --- |
+| `coreml/clip_image_coreml_fp16.pte` | image | coreml | fp16 |
+| `coreml/clip_text_coreml_fp16.pte` | text | coreml | fp16 |
+```
+
+The precision token is the whole story: `precisions.json` is authoritative for
+which tokens are quantized, so the card does not repeat that partition. Nor
+does it name a default, because the library resolves one per platform and a
+second answer here would only compete with it.
+
+### 3. Repository structure
+
+Every tracked file except `README.md` and dotfiles, with its size, so a reader
+can see the download cost before fetching.
+
+```markdown
+## Repository structure
+
+​```
+coreml/config.json                 1 kB
+coreml/model_coreml_fp16.pte       8.3 MB
+xnnpack/config.json                3 kB
+xnnpack/model_xnnpack_fp32.pte     31.1 MB
+​```
+```
+
+Sizes render as `B`, `kB`, `MB` or `GB`.
+
+### 4. Compatibility
+
+Fixed text, parameterised only by the ExecuTorch runtime version. It states
+the runtime the files are **published for**, and deliberately does not claim
+the version each file was exported with: that is unrecorded for older exports,
+and the five conflicting numbers the cards used to carry were all stale.
+
+No react-native-executorch version appears here. Naming one would force an
+edit to every card on each library release even when neither the runtime nor
+the files changed, which is exactly the drift this standard exists to stop.
+
+```markdown
+## Compatibility
+
+These files are published for the **ExecuTorch v1.4.1** runtime. ExecuTorch
+gives no forward compatibility guarantee, so an older runtime may fail to load
+them.
+
+To use them in React Native ExecuTorch, pass the model constant shipped in the
+library's model registry to the corresponding task pipeline. See the
+[documentation](https://docs.swmansion.com/react-native-executorch/docs/fundamentals/loading-models).
+
+To load these files in your own ExecuTorch runtime, read the
+[compatibility note](https://github.com/pytorch/executorch/blob/main/runtime/COMPATIBILITY.md)
+first.
+```
+
+Bump the version here only when the runtime the files are published for
+changes.
+
+## Free sections
+
+Everything a model needs that neither the skeleton nor the repository's JSON
+can express, appended after Compatibility at `##` level and left exactly as
+written.
+
+- `Export notes`, `CoreML notes (iOS)`: export decisions and per-backend
+  caveats. These live nowhere else, so the card is their home.
+- `Model details`, `Languages`, `Classes (N)`: **only** when the model is
+  niche or the upstream link does not already cover it. For a model with a
+  well-documented upstream this duplicates a page we do not control and
+  cannot keep in sync.
+
+Do not write a free section for:
+
+- **The I/O contract.** The `config.json` files declare it, so restating it
+  here breaks rule 5. (Two shapes are in play today, the schema and the older
+  one reporting only upper bounds for dims, which is a reason to converge
+  them, not to re-document I/O by hand in 54 places.)
+- **Latency or benchmark numbers.** They belong on the docs page, where they
+  are versioned and compared across models. Nobody looks in a model card for
+  them, and a stale number here is worse than none.
+- **Required preprocessing.** `models.ts` declares it, and these files are
+  published to be consumed through the library, so its readers already have
+  the authoritative copy. A second copy here is one more thing to keep in
+  sync for an audience that does not need it.
+
+Write a free section only when the answer to "how do I call this correctly?"
+follows from neither the variant table nor the JSON.
+
+## Rules
+
+1. Heading levels are fixed: one `#` title, everything else `##`.
+2. Never hand-edit a generated section. Fix the tree or the `config.json` and
+   re-render, so the card and the artifacts cannot disagree.
+3. One ExecuTorch version appears in a card, in Compatibility.
+4. Free sections carry the model-specific truth. Boilerplate belongs in the
+   generated skeleton, where it is written once.
+5. Nothing in a card restates a fact the artifacts already hold. Derive it
+   instead, so the two cannot disagree.

README.md

@@ -18,13 +18,14 @@ model repositories under
 | -------------------- | ----------------------------------------------------------------------------------------- |
 | `config.schema.json` | JSON Schema for the per-backend `config.json` files shipped alongside each `.pte`.        |
 | `precisions.json`    | Authoritative quantized / non-quantized partition for precision tokens used in file names. |
+| `MODEL_CARD.md`      | The README standard every model repository's card follows.                                |
 | `README.md`          | This file.                                                                                |
 
 ## Source of truth
 
-The artifacts in this repository are the spec. Edit `config.schema.json` and
-`precisions.json` here, and treat them as authoritative for every published
-`config.json`.
+The artifacts in this repository are the spec. Edit `config.schema.json`,
+`precisions.json` and `MODEL_CARD.md` here, and treat them as authoritative
+for every published `config.json` and `README.md`.
 
 ## Versioning