provenance stamp v0: canonical convention + retrofit 4 hero recipes (#81)

- AGENTS.md: one canonical provenance-stamp convention (copy-block) —
  'Produced on HF Jobs' gated on JOB_ID (set in-container by Jobs; a
  local run must not claim it), hardware from ACCELERATOR, reproduce
  command is 'hf jobs uv run', org-level credit, tags uv-script +
  hf-jobs (when on Jobs) as the adoption meters.
- glm-ocr, nanonets-ocr, rolm-ocr: align existing card Reproduction
  sections to the convention (bare 'uv run' -> 'hf jobs uv run',
  conditional origin line, conditional hf-jobs tag, fold the footer
  into the origin line).
- generate-embeddings: fix unconditional 'Produced on Hugging Face
  Jobs' claim (false for local runs), add card frontmatter tags
  (had none), add canonical Reproduction section.

Meter baseline 2026-07-08: 431 public datasets tagged uv-script
(280 davanstrien, 151 external across 40+ owners).


Claude-Session: https://claude.ai/code/session_01QyEUD557s6w9CaJoNQo1yY

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: davanstrien

AGENTS.md

@@ -49,6 +49,34 @@ workflow's optional `repo_id` / `repo_type` inputs.)
   dataset repos hosting code).
 - Every script's docstring shows a runnable **`hf jobs uv run`** example. README examples use the **HF raw
   URL** `https://huggingface.co/datasets/uv-scripts/<repo>/raw/main/<script>.py` (the trackable invocation).
+- **Provenance stamp (canonical — copy this, don't invent variants).** Every output dataset card a recipe
+  pushes ends with a `## Reproduction` section in exactly this shape (inline it in the card f-string;
+  no shared helper):
+
+  ```python
+  on_jobs = os.environ.get("JOB_ID") is not None          # set by HF Jobs in-container
+  hw = os.environ.get("ACCELERATOR") or ""                # e.g. "a10g-small"; empty on CPU
+  origin = (
+      f"Produced on [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs)"
+      + (f" (`{hw}`)" if hw else "")
+  ) if on_jobs else "Generated"
+  ```
+
+  ```markdown
+  ## Reproduction
+
+  {origin} with the [`<script>.py`](<script-raw-url>) recipe from [uv-scripts](https://huggingface.co/uv-scripts). Run it yourself:
+
+  ```bash
+  hf jobs uv run <script-raw-url> <args>
+  ```
+  ```
+
+  Rules: the reproduce command is **`hf jobs uv run`** (never bare `uv run` — the card is the Jobs
+  advertisement); the "Produced on HF Jobs" claim is **gated on `JOB_ID`** (a local run must not claim it);
+  credit goes to the **org**, never a personal name; no badges. Card frontmatter tags: always `uv-script`,
+  plus **`hf-jobs` when `JOB_ID` is set** — these are the adoption meters
+  (`list_datasets(tags="uv-script")` / `tags="hf-jobs"` count stamped public outputs).
 - GPU scripts check `torch.cuda.is_available()` and exit with a clear message. Write outputs to the Hub
   (`push_to_hub`) or a bucket (`-v hf://…`), never local paths (Jobs disk is ephemeral). Name by task, not tool.
 

embeddings/generate-embeddings.py

@@ -315,14 +315,28 @@ def main():
     effective = prompt_str if prompt_str is not None else next(
         (v for k in side_keys if (v := (getattr(model, "prompts", {}) or {}).get(k))), "")
     prompt_line = f"`{effective}`" if effective else "(none)"
+    # Canonical provenance stamp (see AGENTS.md): Jobs claim gated on JOB_ID, set by HF Jobs in-container.
+    script_url = "https://huggingface.co/datasets/uv-scripts/embeddings/raw/main/generate-embeddings.py"
+    on_jobs = os.environ.get("JOB_ID") is not None
+    hw = os.environ.get("ACCELERATOR") or ""
+    origin = (
+        "Produced on [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs)"
+        + (f" (`{hw}`)" if hw else "")
+    ) if on_jobs else "Generated"
+    jobs_tag = "\n- hf-jobs" if on_jobs else ""
     card = DatasetCard(
+        f"---\ntags:\n- embeddings\n- uv-script\n- generated{jobs_tag}\n---\n\n"
         f"# {args.output_dataset}\n\n"
         f"Embeddings of [`{args.input_dataset}`](https://huggingface.co/datasets/{args.input_dataset}) "
         f"column `{args.column}`.\n\n"
         f"- Model: [`{args.model}`](https://huggingface.co/{args.model}) (dim {dim})\n"
         f"- Column: `{args.output_column}`  ·  normalized: {args.normalize}\n"
         f"- Prompt prepended ({'query' if args.query_mode else 'document'} side): {prompt_line}\n\n"
-        f"Produced on Hugging Face Jobs with `uv-scripts/embeddings/generate-embeddings.py`.\n"
+        f"## Reproduction\n\n"
+        f"{origin} with the [`generate-embeddings.py`]({script_url}) recipe "
+        f"from [uv-scripts](https://huggingface.co/uv-scripts). Run it yourself:\n\n"
+        f"```bash\nhf jobs uv run {script_url} \\\n"
+        f"    {args.input_dataset} <output-dataset> --column {args.column} --model {args.model}\n```\n"
     )
     # Retry the push with an XET-disable fallback: a transient upload failure here would
     # otherwise lose the whole (paid) embedding run.

ocr/glm-ocr.py

@@ -199,14 +199,23 @@ def create_dataset_card(
         "table": "table recognition",
     }
 
+    # Canonical provenance stamp (see AGENTS.md): Jobs claim gated on JOB_ID, set by HF Jobs in-container.
+    on_jobs = os.environ.get("JOB_ID") is not None
+    hw = os.environ.get("ACCELERATOR") or ""
+    origin = (
+        "Produced on [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs)"
+        + (f" (`{hw}`)" if hw else "")
+    ) if on_jobs else "Generated"
+    jobs_tag = "\n- hf-jobs" if on_jobs else ""
+
     return f"""---
 tags:
 - ocr
 - document-processing
 - glm-ocr
 - markdown
 - uv-script
-- generated
+- generated{jobs_tag}
 ---
 
 # Document OCR using {model_name}
@@ -252,16 +261,16 @@ def create_dataset_card(
 
 ## Reproduction
 
+{origin} with the [`glm-ocr.py`](https://huggingface.co/datasets/uv-scripts/ocr/raw/main/glm-ocr.py) recipe from [uv-scripts](https://huggingface.co/uv-scripts). Run it yourself:
+
 ```bash
-uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/glm-ocr.py \\
+hf jobs uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/glm-ocr.py \\
     {source_dataset} \\
     <output-dataset> \\
     --image-column {image_column} \\
     --batch-size {batch_size} \\
     --task {task}
 ```
-
-Generated with [UV Scripts](https://huggingface.co/uv-scripts)
 """
 
 

ocr/nanonets-ocr.py

@@ -130,6 +130,15 @@ def create_dataset_card(
     """Create a dataset card documenting the OCR process."""
     model_name = model.split("/")[-1]
 
+    # Canonical provenance stamp (see AGENTS.md): Jobs claim gated on JOB_ID, set by HF Jobs in-container.
+    on_jobs = os.environ.get("JOB_ID") is not None
+    hw = os.environ.get("ACCELERATOR") or ""
+    origin = (
+        "Produced on [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs)"
+        + (f" (`{hw}`)" if hw else "")
+    ) if on_jobs else "Generated"
+    jobs_tag = "\n- hf-jobs" if on_jobs else ""
+
     return f"""---
 viewer: false
 tags:
@@ -138,7 +147,7 @@ def create_dataset_card(
 - nanonets
 - markdown
 - uv-script
-- generated
+- generated{jobs_tag}
 ---
 
 # Document OCR using {model_name}
@@ -202,10 +211,10 @@ def create_dataset_card(
 
 ## Reproduction
 
-This dataset was generated using the [uv-scripts/ocr](https://huggingface.co/datasets/uv-scripts/ocr) Nanonets OCR script:
+{origin} with the [`nanonets-ocr.py`](https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py) recipe from [uv-scripts](https://huggingface.co/uv-scripts). Run it yourself:
 
 ```bash
-uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py \\
+hf jobs uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/nanonets-ocr.py \\
     {source_dataset} \\
     <output-dataset> \\
     --image-column {image_column} \\
@@ -219,8 +228,6 @@ def create_dataset_card(
 
 - **Processing Speed**: ~{num_samples / (float(processing_time.split()[0]) * 60):.1f} images/second
 - **GPU Configuration**: vLLM with {gpu_memory_utilization:.0%} GPU memory utilization
-
-Generated with 🤖 [UV Scripts](https://huggingface.co/uv-scripts)
 """
 
 

ocr/rolm-ocr.py

@@ -131,14 +131,23 @@ def create_dataset_card(
     """Create a dataset card documenting the OCR process."""
     model_name = model.split("/")[-1]
 
+    # Canonical provenance stamp (see AGENTS.md): Jobs claim gated on JOB_ID, set by HF Jobs in-container.
+    on_jobs = os.environ.get("JOB_ID") is not None
+    hw = os.environ.get("ACCELERATOR") or ""
+    origin = (
+        "Produced on [Hugging Face Jobs](https://huggingface.co/docs/huggingface_hub/guides/jobs)"
+        + (f" (`{hw}`)" if hw else "")
+    ) if on_jobs else "Generated"
+    jobs_tag = "\n- hf-jobs" if on_jobs else ""
+
     return f"""---
 viewer: false
 tags:
 - ocr
 - text-extraction
 - rolmocr
 - uv-script
-- generated
+- generated{jobs_tag}
 ---
 
 # OCR Text Extraction using {model_name}
@@ -195,10 +204,10 @@ def create_dataset_card(
 
 ## Reproduction
 
-This dataset was generated using the [uv-scripts/ocr](https://huggingface.co/datasets/uv-scripts/ocr) RolmOCR script:
+{origin} with the [`rolm-ocr.py`](https://huggingface.co/datasets/uv-scripts/ocr/raw/main/rolm-ocr.py) recipe from [uv-scripts](https://huggingface.co/uv-scripts). Run it yourself:
 
 ```bash
-uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/rolm-ocr.py \\
+hf jobs uv run https://huggingface.co/datasets/uv-scripts/ocr/raw/main/rolm-ocr.py \\
     {source_dataset} \\
     <output-dataset> \\
     --image-column {image_column} \\
@@ -212,8 +221,6 @@ def create_dataset_card(
 
 - **Processing Speed**: ~{num_samples / (float(processing_time.split()[0]) * 60):.1f} images/second
 - **GPU Configuration**: vLLM with {gpu_memory_utilization:.0%} GPU memory utilization
-
-Generated with 🤖 [UV Scripts](https://huggingface.co/uv-scripts)
 """