Bootstrap automatic contribution interface

app.js

@@ -1,9 +1,11 @@
 (() => {
   "use strict";
 
-  const GITHUB_CONTRIBUTING =
-    "https://github.com/DanielTabaresLopez/" +
-    "Gene-Embeddings-Contributions/blob/main/CONTRIBUTING.md";
+  const HF_UPLOAD_URL =
+    "https://huggingface.co/datasets/" +
+    "embeddingsSSRF/gene_embeddings_staging/upload/main";
+
+  const SUBMISSION_GUIDE = "contribute.html";
 
   const DATASET_BASE =
     "https://huggingface.co/datasets/" +
@@ -18,10 +20,13 @@
   let catalog = [];
 
   document.getElementById("contribute-link").href =
-    GITHUB_CONTRIBUTING;
+    HF_UPLOAD_URL;
 
   document.getElementById("contribute-link-bottom").href =
-    GITHUB_CONTRIBUTING;
+    HF_UPLOAD_URL;
+
+  document.getElementById("submission-guide-link").href =
+    SUBMISSION_GUIDE;
 
   document
     .getElementById("close-detail")

contribute.html

@@ -0,0 +1,234 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta
+    name="viewport"
+    content="width=device-width, initial-scale=1"
+  />
+  <title>Submit a Gene Embedding</title>
+  <link rel="stylesheet" href="style.css" />
+</head>
+
+<body>
+  <header class="hero">
+    <div class="hero-inner">
+      <p class="eyebrow">
+        Community contribution portal
+      </p>
+
+      <h1>Submit an embedding</h1>
+
+      <p class="lead">
+        Upload one standardized gene-embedding package directly
+        to the library-owned Hugging Face Dataset as a Pull
+        Request.
+      </p>
+
+      <div class="actions">
+        <a
+          class="button primary"
+          href="https://huggingface.co/datasets/embeddingsSSRF/gene_embeddings_staging/upload/main"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Open Hugging Face uploader
+        </a>
+
+        <a
+          class="button"
+          href="submission-template.yaml"
+          download
+        >
+          Download submission template
+        </a>
+
+        <a
+          class="button"
+          href="index.html"
+        >
+          Return to catalog
+        </a>
+      </div>
+    </div>
+  </header>
+
+  <main class="guide-layout">
+    <section class="guide-card">
+      <h2>What you need</h2>
+
+      <p>
+        You need a Hugging Face account. You do not need a
+        GitHub account, GitHub fork, personal Dataset, or commit
+        SHA.
+      </p>
+
+      <p>
+        Prepare exactly one folder with a unique embedding ID:
+      </p>
+
+      <pre><code>&lt;embedding_id&gt;/
+├── embeddings.npz
+├── genes.tsv
+├── metadata.json
+├── README.md
+└── submission.yaml</code></pre>
+
+      <p>
+        The embedding ID must contain 3–80 lowercase letters,
+        numbers, dots, underscores, or hyphens. It must begin
+        with a letter or number.
+      </p>
+    </section>
+
+    <section class="guide-card">
+      <h2>Package contract</h2>
+
+      <ul>
+        <li>
+          <code>embeddings.npz</code> contains exactly one
+          two-dimensional array named
+          <code>embeddings</code>.
+        </li>
+
+        <li>
+          The embedding matrix uses
+          <code>float32</code>.
+        </li>
+
+        <li>
+          <code>genes.tsv</code> contains one unique,
+          non-empty
+          <code>ensembl_gene_id</code> column.
+        </li>
+
+        <li>
+          Gene-table rows correspond exactly to matrix rows.
+        </li>
+
+        <li>
+          <code>metadata.json</code> describes the stored
+          embedding.
+        </li>
+
+        <li>
+          <code>submission.yaml</code> contains contributor,
+          scientific, provenance, licensing, and attestation
+          information.
+        </li>
+      </ul>
+    </section>
+
+    <section class="guide-card warning-card">
+      <h2>Upload as a Pull Request</h2>
+
+      <ol>
+        <li>
+          Click <strong>Open Hugging Face uploader</strong>.
+        </li>
+
+        <li>
+          Upload all five files under:
+          <pre><code>incoming/&lt;embedding_id&gt;/</code></pre>
+        </li>
+
+        <li>
+          Add a descriptive message such as:
+          <pre><code>Submit &lt;embedding_id&gt;</code></pre>
+        </li>
+
+        <li>
+          Select <strong>Open as a pull request</strong>.
+        </li>
+
+        <li>
+          Do not commit the files directly to
+          <code>main</code>.
+        </li>
+
+        <li>
+          Confirm that the Pull Request is Open or Ready for
+          review.
+        </li>
+      </ol>
+    </section>
+
+    <section class="guide-card">
+      <h2>Command-line alternative</h2>
+
+      <p>
+        Uploading through the browser is the primary route. The
+        equivalent command-line submission is:
+      </p>
+
+      <pre><code>hf upload \
+  embeddingsSSRF/gene_embeddings_staging \
+  ./&lt;embedding_id&gt; \
+  incoming/&lt;embedding_id&gt; \
+  --repo-type dataset \
+  --create-pr \
+  --commit-message "Submit &lt;embedding_id&gt;"</code></pre>
+
+      <p>
+        Programmatic uploads may initially appear as Draft.
+        Change the Pull Request status to Open or Ready for
+        review before processing.
+      </p>
+    </section>
+
+    <section class="guide-card">
+      <h2>Catalog category</h2>
+
+      <p>Recommended categories are:</p>
+
+      <p>
+        DNA, Expression, Functional Genomics, Knowledge,
+        Literature, Multimodal, Network, Protein, RNA,
+        Regulatory, and Single-cell.
+      </p>
+
+      <p>
+        Matching is case-insensitive. Another submitted value is
+        preserved but displayed under
+        <strong>Other</strong>.
+      </p>
+    </section>
+
+    <section class="guide-card">
+      <h2>Privacy and publication</h2>
+
+      <p>
+        Do not upload personal email addresses, credentials,
+        access tokens, patient information, patient-level data,
+        or other sensitive material.
+      </p>
+
+      <p>
+        A strict validation PASS is centrally archived under:
+      </p>
+
+      <pre><code>data/embeddings/&lt;embedding_id&gt;/</code></pre>
+
+      <p>
+        The registry and static catalog then link to this
+        library-owned copy.
+      </p>
+    </section>
+
+    <section class="guide-card staging-card">
+      <h2>Staging access</h2>
+
+      <p>
+        This page currently targets the staging Dataset. While
+        that Dataset is private, submission is limited to users
+        who already have access to the organization repository.
+      </p>
+
+      <p>
+        The production button will target the public production
+        Dataset after final approval.
+      </p>
+    </section>
+  </main>
+</body>
+</html>

index.html

@@ -2,53 +2,206 @@
 <html lang="en">
 <head>
   <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta
+    name="viewport"
+    content="width=device-width, initial-scale=1"
+  />
   <title>Gene Embeddings</title>
   <link rel="stylesheet" href="style.css" />
 </head>
+
 <body>
   <header class="hero">
     <div class="hero-inner">
-      <p class="eyebrow">Unified human gene representations</p>
+      <p class="eyebrow">
+        Unified human gene representations
+      </p>
+
       <h1>Gene Embeddings</h1>
-      <p class="lead">Browse standardized gene-level representations across sequence, expression, literature, pathway, network, regulatory, knowledge-graph, and single-cell modalities.</p>
+
+      <p class="lead">
+        Browse standardized gene-level representations across
+        sequence, expression, literature, pathway, network,
+        regulatory, knowledge-graph, and single-cell modalities.
+      </p>
+
       <div class="actions">
-        <a class="button primary" id="contribute-link" href="#" target="_blank" rel="noopener noreferrer">Contribute an embedding</a>
-        <a class="button" href="https://huggingface.co/datasets/embeddingsSSRF/gene_embeddings" target="_blank" rel="noopener noreferrer">Open Core Dataset</a>
+        <a
+          class="button primary"
+          id="contribute-link"
+          href="#"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Upload an embedding
+        </a>
+
+        <a
+          class="button"
+          id="submission-guide-link"
+          href="contribute.html"
+        >
+          Submission guide
+        </a>
+
+        <a
+          class="button"
+          href="https://huggingface.co/datasets/embeddingsSSRF/gene_embeddings"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Open Core Dataset
+        </a>
       </div>
-      <p class="notice">Community contributions are automatically checked for compliance with the technical policy. Inclusion is not independent scientific or legal endorsement.</p>
+
+      <p class="notice">
+        Community contributions are automatically checked for
+        compliance with the technical policy. Inclusion is not
+        independent scientific or legal endorsement.
+      </p>
     </div>
   </header>
 
   <main>
-    <section class="stats" aria-label="Catalog summary">
-      <article><strong id="stat-count">—</strong><span>embedding sets</span></article>
-      <article><strong id="stat-genes">—</strong><span>maximum genes</span></article>
-      <article><strong id="stat-dims">—</strong><span>dimension range</span></article>
+    <section
+      class="stats"
+      aria-label="Catalog summary"
+    >
+      <article>
+        <strong id="stat-count">—</strong>
+        <span>embedding sets</span>
+      </article>
+
+      <article>
+        <strong id="stat-genes">—</strong>
+        <span>maximum genes</span>
+      </article>
+
+      <article>
+        <strong id="stat-dims">—</strong>
+        <span>dimension range</span>
+      </article>
     </section>
 
     <section class="controls">
-      <input id="search" type="search" placeholder="Search names, modalities, or methods" aria-label="Search catalog" />
-      <select id="category" aria-label="Filter by category"><option value="All">All categories</option></select>
+      <input
+        id="search"
+        type="search"
+        placeholder="Search names, modalities, or methods"
+        aria-label="Search catalog"
+      />
+
+      <select
+        id="category"
+        aria-label="Filter by category"
+      >
+        <option value="All">
+          All categories
+        </option>
+      </select>
     </section>
 
-    <p id="result-count" class="result-count"></p>
-    <section id="grid" class="grid" aria-live="polite"></section>
+    <p
+      id="result-count"
+      class="result-count"
+    ></p>
+
+    <section
+      id="grid"
+      class="grid"
+      aria-live="polite"
+    ></section>
+
+    <section
+      class="contribute"
+      id="contribute"
+    >
+      <h2>Submit directly through Hugging Face</h2>
+
+      <p>
+        A Hugging Face account is required. A GitHub account,
+        GitHub fork, separate Dataset, and commit SHA are not
+        required.
+      </p>
 
-    <section class="contribute" id="contribute">
-      <h2>Automatic contribution workflow</h2>
       <ol>
-        <li>Put <code>embeddings.npz</code>, <code>genes.tsv</code>, <code>metadata.json</code>, and <code>README.md</code> in a public Hugging Face Dataset.</li>
-        <li>Freeze the candidate at a full commit SHA.</li>
-        <li>Add one submission YAML through a GitHub Pull Request.</li>
-        <li>GitHub validates the frozen package. A strict PASS is merged and published automatically.</li>
+        <li>
+          Prepare one folder containing
+          <code>embeddings.npz</code>,
+          <code>genes.tsv</code>,
+          <code>metadata.json</code>,
+          <code>README.md</code>, and
+          <code>submission.yaml</code>.
+        </li>
+
+        <li>
+          Name the folder using a unique lowercase embedding ID.
+        </li>
+
+        <li>
+          Click <strong>Open Hugging Face uploader</strong> and
+          place the files under
+          <code>incoming/&lt;embedding_id&gt;/</code>.
+        </li>
+
+        <li>
+          Select <strong>Open as a pull request</strong>.
+          Do not commit the files directly to
+          <code>main</code>.
+        </li>
+
+        <li>
+          Ensure the resulting Pull Request is marked
+          <strong>Open</strong> or
+          <strong>Ready for review</strong>, not Draft.
+        </li>
       </ol>
-      <a class="button primary" id="contribute-link-bottom" href="#" target="_blank" rel="noopener noreferrer">Open contribution instructions</a>
+
+      <div class="button-row">
+        <a
+          class="button primary"
+          id="contribute-link-bottom"
+          href="#"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Open Hugging Face uploader
+        </a>
+
+        <a
+          class="button"
+          href="contribute.html"
+        >
+          Read full submission guide
+        </a>
+
+        <a
+          class="button"
+          href="submission-template.yaml"
+          download
+        >
+          Download submission template
+        </a>
+      </div>
+
+      <p class="staging-note">
+        Staging note: submissions are currently processed after
+        a maintainer starts the validation workflow. Automatic
+        discovery will be enabled after the staging interface
+        has been verified.
+      </p>
     </section>
   </main>
 
   <dialog id="detail-dialog">
-    <button id="close-detail" class="close" aria-label="Close">×</button>
+    <button
+      id="close-detail"
+      class="close"
+      aria-label="Close"
+    >
+      ×
+    </button>
+
     <div id="detail-content"></div>
   </dialog>
 

style.css

@@ -65,3 +65,57 @@ dialog::backdrop { background: rgba(12,20,40,.55); }
   color: var(--success);
 }
 
+.button-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  margin-top: 22px;
+}
+
+.staging-note {
+  margin-top: 22px;
+  padding: 14px 16px;
+  border-left: 4px solid var(--brand);
+  background: var(--wash);
+  color: var(--muted);
+  line-height: 1.55;
+}
+
+.guide-layout {
+  display: grid;
+  gap: 18px;
+  padding-top: 38px;
+}
+
+.guide-card {
+  background: var(--paper);
+  border: 1px solid var(--line);
+  border-radius: 16px;
+  padding: 26px;
+}
+
+.guide-card h2 {
+  margin-top: 0;
+}
+
+.guide-card p,
+.guide-card li {
+  line-height: 1.65;
+}
+
+.guide-card pre {
+  overflow-x: auto;
+  padding: 16px;
+  border-radius: 10px;
+  background: #111a2e;
+  color: #edf2ff;
+}
+
+.warning-card {
+  border-left: 5px solid #c77a00;
+}
+
+.staging-card {
+  border-left: 5px solid var(--brand);
+}
+

submission-template.yaml

@@ -0,0 +1,33 @@
+schema_version: 1
+embedding_id: replace_with_unique_embedding_id
+display_name: Replace with the displayed embedding name
+contributor:
+  name: Replace with contributor name
+  affiliation: Replace with institution or organization
+scientific:
+  broad_modality: Protein
+  detailed_modality: Replace with a precise modality description
+  original_method: Replace with the model or generation method
+  model_checkpoint: Replace with checkpoint/version or not-applicable
+  source_publication: ''
+  description: Replace this text with a clear description of the embedding, how it
+    was generated, and its intended use.
+provenance:
+  embedding_generated_by: Replace with model, software, or authors
+  input_data_source: Replace with the original data source
+  input_data_release: Replace with version or release
+  species: Homo sapiens
+  pooling_strategy: Replace with pooling strategy or not-applicable
+  identifier_before_mapping: Replace with original identifier type
+  mapping_method: Replace with the identifier mapping procedure
+licensing:
+  source_license: cc-by-4.0
+  redistribution_allowed: true
+  terms_url: Replace with the applicable license or terms URL
+attestations:
+  information_is_accurate: true
+  rights_to_redistribute: true
+  no_sensitive_human_data: true
+  no_patient_level_data: true
+  source_terms_reviewed: true
+  acceptance_of_automatic_checks: true