Upload folder using huggingface_hub

app.js

@@ -1019,6 +1019,18 @@ function initEventListeners() {
       connectS3();
     }
   });
+
+  // Help toggle buttons
+  document.addEventListener("click", (e) => {
+    const toggle = e.target.closest(".help-toggle");
+    if (!toggle) return;
+    e.preventDefault();
+    const helpId = toggle.dataset.help;
+    if (!helpId) return;
+    const helpEl = document.getElementById(helpId);
+    if (!helpEl) return;
+    helpEl.classList.toggle("visible");
+  });
 }
 
 // ============================================================

index.html

@@ -64,31 +64,77 @@
           <h2>Connect to S3</h2>
           <span id="s3-status" class="card-status hidden"></span>
         </div>
+        <div class="section-help">
+          Provide your AWS credentials so we can list your S3 bucket contents.
+          Credentials are only used in your browser to browse files, then passed as encrypted secrets to the import Job. They are never stored.
+        </div>
         <div class="form-grid">
           <div class="form-group">
-            <label>AWS Access Key ID <span class="required">*</span></label>
+            <div class="label-row">
+              <label>AWS Access Key ID <span class="required">*</span></label>
+              <button type="button" class="help-toggle" data-help="help-access-key">?</button>
+            </div>
             <input type="text" id="aws-access-key" placeholder="AKIA..." autocomplete="off" spellcheck="false">
+            <div id="help-access-key" class="field-help">
+              Your IAM access key ID, starting with <code>AKIA</code>. You can create one in the
+              <a href="https://console.aws.amazon.com/iam/home#/security_credentials" target="_blank" rel="noopener">AWS IAM Console</a>
+              under "Access keys". We recommend using a key with read-only S3 permissions.
+            </div>
           </div>
           <div class="form-group">
-            <label>AWS Secret Access Key <span class="required">*</span></label>
+            <div class="label-row">
+              <label>AWS Secret Access Key <span class="required">*</span></label>
+              <button type="button" class="help-toggle" data-help="help-secret-key">?</button>
+            </div>
             <input type="password" id="aws-secret-key" placeholder="Your secret key" autocomplete="off">
+            <div id="help-secret-key" class="field-help">
+              The secret key paired with your Access Key ID. It was shown only once when you created the access key.
+              This value is sent to the HF Job as an encrypted secret and is never logged or stored.
+            </div>
           </div>
           <div class="form-group">
-            <label>AWS Region</label>
+            <div class="label-row">
+              <label>AWS Region</label>
+              <button type="button" class="help-toggle" data-help="help-region">?</button>
+            </div>
             <input type="text" id="aws-region" value="us-east-1" placeholder="us-east-1">
+            <div id="help-region" class="field-help">
+              The AWS region where your S3 bucket is hosted, e.g. <code>us-east-1</code>, <code>eu-west-1</code>, <code>ap-southeast-1</code>.
+              You can find this in the AWS Console next to your bucket name, or in the bucket's Properties tab.
+            </div>
           </div>
           <div class="form-group">
-            <label>S3 Bucket Name <span class="required">*</span></label>
+            <div class="label-row">
+              <label>S3 Bucket Name <span class="required">*</span></label>
+              <button type="button" class="help-toggle" data-help="help-bucket-name">?</button>
+            </div>
             <input type="text" id="s3-bucket" placeholder="my-data-bucket" spellcheck="false">
+            <div id="help-bucket-name" class="field-help">
+              The name of your S3 bucket (not the full ARN or URL). For example, if your bucket URL is
+              <code>s3://my-data-bucket</code>, enter <code>my-data-bucket</code>.
+            </div>
           </div>
           <div class="form-group">
-            <label>Endpoint URL <span class="text-muted">(optional, for S3-compatible services)</span></label>
+            <div class="label-row">
+              <label>Endpoint URL <span class="text-muted">(optional)</span></label>
+              <button type="button" class="help-toggle" data-help="help-endpoint">?</button>
+            </div>
             <input type="text" id="s3-endpoint" placeholder="https://s3.example.com" spellcheck="false">
+            <div id="help-endpoint" class="field-help">
+              Only needed for S3-compatible services (MinIO, DigitalOcean Spaces, Cloudflare R2, etc.).
+              Leave empty for standard AWS S3. Example: <code>https://nyc3.digitaloceanspaces.com</code>
+            </div>
           </div>
           <div class="form-group">
-            <label>Source Prefix <span class="text-muted">(optional)</span></label>
+            <div class="label-row">
+              <label>Source Prefix <span class="text-muted">(optional)</span></label>
+              <button type="button" class="help-toggle" data-help="help-prefix">?</button>
+            </div>
             <input type="text" id="s3-prefix" placeholder="data/exports/" spellcheck="false">
-            <span class="hint">Only import files under this prefix</span>
+            <div id="help-prefix" class="field-help">
+              Filter to a subfolder within your bucket. Only files under this path will be listed and imported.
+              For example, <code>data/exports/</code> will only show files starting with that path. Leave empty to browse the entire bucket.
+            </div>
           </div>
         </div>
         <div class="form-actions">
@@ -170,22 +216,47 @@
           <h2>Configure Import</h2>
         </div>
 
+        <div class="section-help">
+          Choose where to import your files on Hugging Face. The bucket will be created automatically if it doesn't exist yet.
+          The import runs as an <a href="https://huggingface.co/docs/hub/jobs" target="_blank" rel="noopener">HF Job</a> on Hugging Face infrastructure &mdash; your browser does not need to stay open.
+        </div>
+
         <div class="form-grid">
           <div class="form-group">
-            <label>Destination Bucket <span class="required">*</span></label>
+            <div class="label-row">
+              <label>Destination Bucket <span class="required">*</span></label>
+              <button type="button" class="help-toggle" data-help="help-dest-bucket">?</button>
+            </div>
             <input type="text" id="dest-bucket" placeholder="my-bucket or namespace/my-bucket" spellcheck="false">
-            <span class="hint">Use <code>namespace/bucket</code> or just <code>bucket</code> (defaults to your username)</span>
+            <div id="help-dest-bucket" class="field-help">
+              The HF Storage Bucket to import files into. You can use:<br>
+              &bull; <code>bucket-name</code> &mdash; creates under your username (<code>username/bucket-name</code>)<br>
+              &bull; <code>org/bucket-name</code> &mdash; creates under a specific organization<br>
+              The bucket will be created for you if it doesn't exist yet.
+            </div>
           </div>
           <div class="form-group">
-            <label>Destination Prefix <span class="text-muted">(optional)</span></label>
+            <div class="label-row">
+              <label>Destination Prefix <span class="text-muted">(optional)</span></label>
+              <button type="button" class="help-toggle" data-help="help-dest-prefix">?</button>
+            </div>
             <input type="text" id="dest-prefix" placeholder="imported/2024/" spellcheck="false">
-            <span class="hint">Import files under this folder in the bucket</span>
+            <div id="help-dest-prefix" class="field-help">
+              Place imported files under this path within the bucket. For example, <code>imported/2024/</code>
+              will import <code>file.txt</code> as <code>imported/2024/file.txt</code> in the bucket.
+              Leave empty to import at the bucket root.
+            </div>
           </div>
         </div>
 
         <div class="form-group mt-4" style="flex-direction: row; align-items: center; gap: 8px;">
           <input type="checkbox" id="dest-private" checked style="accent-color: var(--accent); width: 16px; height: 16px;">
           <label for="dest-private" style="margin: 0; cursor: pointer;">Create bucket as private</label>
+          <button type="button" class="help-toggle" data-help="help-private">?</button>
+        </div>
+        <div id="help-private" class="field-help" style="margin-top: 4px;">
+          Private buckets are only accessible to you (and your organization members).
+          Uncheck to make the bucket publicly readable. This only applies when creating a new bucket &mdash; existing buckets keep their current visibility.
         </div>
 
         <div id="dest-preview" class="dest-preview mt-4 hidden"></div>
@@ -194,19 +265,36 @@
 
         <div class="config-row">
           <div class="form-group">
-            <label>Hardware</label>
+            <div class="label-row">
+              <label>Hardware</label>
+              <button type="button" class="help-toggle" data-help="help-hardware">?</button>
+            </div>
             <select id="job-flavor">
               <option value="cpu-basic">CPU Basic ($0.04/hr)</option>
               <option value="cpu-upgrade">CPU Upgrade ($0.07/hr)</option>
             </select>
+            <div id="help-hardware" class="field-help">
+              The machine type for the import Job. S3-to-bucket transfer is network-bound, so CPU is sufficient.
+              <code>CPU Upgrade</code> provides more memory and bandwidth for very large imports.
+              You are billed per second of Job runtime.
+            </div>
           </div>
           <div class="form-group">
-            <label>Workers</label>
+            <div class="label-row">
+              <label>Workers</label>
+              <button type="button" class="help-toggle" data-help="help-workers">?</button>
+            </div>
             <input type="number" id="job-workers" value="4" min="1" max="16">
-            <span class="hint">Parallel download threads</span>
+            <div id="help-workers" class="field-help">
+              Number of parallel download threads. Higher values speed up the transfer when importing many small files.
+              For large files (100MB+), 2-4 workers is usually sufficient. Max: 16.
+            </div>
           </div>
           <div class="form-group">
-            <label>Timeout</label>
+            <div class="label-row">
+              <label>Timeout</label>
+              <button type="button" class="help-toggle" data-help="help-timeout">?</button>
+            </div>
             <select id="job-timeout">
               <option value="1800">30 minutes</option>
               <option value="3600">1 hour</option>
@@ -214,11 +302,24 @@
               <option value="21600">6 hours</option>
               <option value="43200">12 hours</option>
             </select>
+            <div id="help-timeout" class="field-help">
+              Maximum time the Job is allowed to run before being automatically stopped.
+              Choose a value that covers your expected transfer time. For large datasets (100GB+), pick 6h or more.
+              You are only billed for actual runtime, not the full timeout.
+            </div>
           </div>
         </div>
 
         <div id="patterns-info" class="hidden">
-          <label style="font-size: 13px; font-weight: 500; color: var(--text-secondary);">Import Command Preview</label>
+          <div class="label-row">
+            <label style="font-size: 13px; font-weight: 500; color: var(--text-secondary);">Import Command Preview</label>
+            <button type="button" class="help-toggle" data-help="help-command">?</button>
+          </div>
+          <div id="help-command" class="field-help" style="margin-top: 4px;">
+            This is the exact shell command that will run inside the HF Job.
+            It installs <code>huggingface_hub</code> with S3 support and runs <code>hf buckets import</code>
+            with your selected files and settings. Include/exclude patterns are auto-generated from your file selection.
+          </div>
           <div id="patterns-preview" class="patterns-preview mt-4"></div>
         </div>
 

style.css

@@ -338,6 +338,84 @@ body {
 .form-group .hint {
   font-size: 12px;
   color: var(--text-muted);
+  line-height: 1.5;
+}
+
+/* ---- Field Help / Tooltips ---- */
+
+.label-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.help-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  border-radius: 50%;
+  border: 1px solid var(--border);
+  background: transparent;
+  color: var(--text-muted);
+  font-size: 10px;
+  font-weight: 700;
+  cursor: pointer;
+  flex-shrink: 0;
+  transition: all 0.15s;
+  padding: 0;
+  line-height: 1;
+  font-family: var(--font-sans);
+}
+
+.help-toggle:hover {
+  border-color: var(--accent);
+  color: var(--accent);
+  background: var(--accent-subtle);
+}
+
+.field-help {
+  display: none;
+  font-size: 12px;
+  color: var(--text-secondary);
+  line-height: 1.6;
+  padding: 8px 10px;
+  margin-top: 2px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+}
+
+.field-help.visible {
+  display: block;
+}
+
+.field-help code {
+  background: var(--bg-input);
+  padding: 1px 5px;
+  border-radius: 3px;
+  font-family: var(--font-mono);
+  font-size: 11px;
+}
+
+.field-help a {
+  color: var(--accent);
+}
+
+.section-help {
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.6;
+  margin-bottom: 16px;
+  padding: 12px 14px;
+  background: var(--bg-secondary);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+}
+
+.section-help a {
+  color: var(--accent);
 }
 
 .form-row {