diff --git a/.agents/scripts/higgsfield-helper.sh b/.agents/scripts/higgsfield-helper.sh
index cdb33ffca..e947c1c9d 100755
--- a/.agents/scripts/higgsfield-helper.sh
+++ b/.agents/scripts/higgsfield-helper.sh
@@ -267,6 +267,7 @@ Options (pass after command):
   --headless         Run without browser window (default)
   --model, -m        Model: soul, nano_banana, seedream, kling-2.6, etc.
   --output, -o       Output directory
+  --project          Project name for organized output dirs ({output}/{project}/{type}/)
   --image-file       Image file for upload
   --timeout          Timeout in milliseconds
   --effect           App/effect slug
@@ -276,12 +277,15 @@ Options (pass after command):
   --character-image  Character face image for pipeline
   --dialogue         Dialogue text for lipsync
   --unlimited        Prefer unlimited models only
+  --no-sidecar       Disable JSON sidecar metadata files
+  --no-dedup         Disable SHA-256 duplicate detection
 
 Examples:
   higgsfield-helper.sh setup
   higgsfield-helper.sh login
   higgsfield-helper.sh image "A cyberpunk city at night, neon lights, rain"
   higgsfield-helper.sh image "Portrait of a woman" --model nano_banana
+  higgsfield-helper.sh image "Portrait" --project my-video --output ~/Projects/
   higgsfield-helper.sh video "Camera pans across mountain landscape"
   higgsfield-helper.sh video "Person walks forward" --image-file photo.jpg
   higgsfield-helper.sh lipsync "Hello world!" --image-file face.jpg
diff --git a/.agents/scripts/higgsfield/playwright-automator.mjs b/.agents/scripts/higgsfield/playwright-automator.mjs
index c4e15ade6..b07bcc1ce 100644
--- a/.agents/scripts/higgsfield/playwright-automator.mjs
+++ b/.agents/scripts/higgsfield/playwright-automator.mjs
@@ -9,6 +9,7 @@ import { join, basename, extname, dirname } from 'path';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
 
 // Constants
 const BASE_URL = 'https://higgsfield.ai';
@@ -253,6 +254,12 @@ function parseArgs() {
       options.feature = args[++i];
     } else if (args[i] === '--subtype') {
       options.subtype = args[++i];
+    } else if (args[i] === '--project') {
+      options.project = args[++i];
+    } else if (args[i] === '--no-sidecar') {
+      options.noSidecar = true;
+    } else if (args[i] === '--no-dedup') {
+      options.noDedup = true;
     } else if (args[i] === '--force') {
       options.force = true;
     } else if (args[i] === '--dry-run') {
@@ -1284,9 +1291,10 @@ async function generateImage(options = {}) {
 
     // Download only the new results
     if (options.wait !== false) {
-      const outputDir = options.output || DOWNLOAD_DIR;
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'images');
       if (newImageIndices.length > 0) {
-        await downloadSpecificImages(page, outputDir, newImageIndices);
+        await downloadSpecificImages(page, outputDir, newImageIndices, options);
       } else if (generationComplete) {
         // Count-based detection failed (page may have refreshed during generation).
         // Use batch size as a cap: download at most N images from the top of the grid.
@@ -1295,7 +1303,7 @@ async function generateImage(options = {}) {
         console.log(`Count-based detection missed new images. Downloading top ${downloadCount} (batch=${batchSize})...`);
         const fallbackIndices = [];
         for (let i = 0; i < downloadCount; i++) fallbackIndices.push(i);
-        await downloadSpecificImages(page, outputDir, fallbackIndices);
+        await downloadSpecificImages(page, outputDir, fallbackIndices, options);
       } else {
         console.log('No new images detected. Generation may still be in progress.');
         console.log('Try: node playwright-automator.mjs download');
@@ -1324,7 +1332,7 @@ async function generateImage(options = {}) {
 // Strategy 2 (FALLBACK): Navigate to the page fresh to trigger the API call,
 //   then extract the URL from the intercepted response.
 // Strategy 3 (LAST RESORT): Extract <video src> from the list item (motion template, low quality).
-async function downloadVideoFromHistory(page, outputDir, metadata = {}) {
+async function downloadVideoFromHistory(page, outputDir, metadata = {}, options = {}) {
   const downloaded = [];
 
   try {
@@ -1442,11 +1450,17 @@ async function downloadVideoFromHistory(page, outputDir, metadata = {}) {
                 const curlResult = execSync(`curl -sL -w '%{http_code}' -o "${savePath}" "${videoUrl}"`, { timeout: 120000, encoding: 'utf-8' });
                 const httpCode = curlResult.trim();
                 if (httpCode === '200' && existsSync(savePath)) {
-                  const fileSize = statSync(savePath).size;
-                  if (fileSize > 10000) { // Sanity check: real videos are >10KB
-                    console.log(`Downloaded full-quality video (${(fileSize / 1024 / 1024).toFixed(1)}MB, HTTP ${httpCode}): ${savePath}`);
-                    downloaded.push(savePath);
-                  } else {
+                    const fileSize = statSync(savePath).size;
+                    if (fileSize > 10000) { // Sanity check: real videos are >10KB
+                      const result = finalizeDownload(savePath, {
+                        command: 'video', type: 'video', ...combinedMeta,
+                        strategy: 'api-interception', cloudFrontUrl: videoUrl,
+                      }, outputDir, options);
+                      if (!result.skipped) {
+                        console.log(`Downloaded full-quality video (${(fileSize / 1024 / 1024).toFixed(1)}MB, HTTP ${httpCode}): ${savePath}`);
+                      }
+                      downloaded.push(result.path);
+                    } else {
                     console.log(`CloudFront returned ${httpCode} but file too small (${fileSize}B), skipping: ${videoUrl.substring(videoUrl.lastIndexOf('/') + 1)}`);
                   }
                 } else {
@@ -1489,8 +1503,14 @@ async function downloadVideoFromHistory(page, outputDir, metadata = {}) {
         const savePath = join(outputDir, filename);
         try {
           execSync(`curl -sL -o "${savePath}" "${videoSrc}"`, { timeout: 120000 });
-          console.log(`Downloaded video (CDN fallback): ${savePath}`);
-          downloaded.push(savePath);
+          const result = finalizeDownload(savePath, {
+            command: 'video', type: 'video', ...combinedMeta,
+            strategy: 'cdn-fallback', cdnUrl: videoSrc,
+          }, outputDir, options);
+          if (!result.skipped) {
+            console.log(`Downloaded video (CDN fallback): ${savePath}`);
+          }
+          downloaded.push(result.path);
         } catch (curlErr) {
           console.log(`CDN video download failed: ${curlErr.message}`);
         }
@@ -1928,9 +1948,10 @@ async function generateVideo(options = {}) {
 
     // Download the video from History
     if (generationComplete && options.wait !== false) {
-      const outputDir = options.output || DOWNLOAD_DIR;
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'videos');
       const videoMeta = { model, promptSnippet: prompt.substring(0, 80) };
-      const downloads = await downloadVideoFromHistory(page, outputDir, videoMeta);
+      const downloads = await downloadVideoFromHistory(page, outputDir, videoMeta, options);
       if (downloads.length > 0) {
         console.log(`Video downloaded successfully: ${downloads.join(', ')}`);
       } else {
@@ -2083,9 +2104,10 @@ async function generateLipsync(options = {}) {
 
     // Download from History
     if (generationComplete && options.wait !== false) {
-      const outputDir = options.output || DOWNLOAD_DIR;
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'lipsync');
       const meta = { model: options.model || 'lipsync', promptSnippet: prompt.substring(0, 80) };
-      const downloads = await downloadVideoFromHistory(page, outputDir, meta);
+      const downloads = await downloadVideoFromHistory(page, outputDir, meta, options);
       if (downloads.length > 0) {
         console.log(`Lipsync video downloaded: ${downloads.join(', ')}`);
       }
@@ -2234,11 +2256,156 @@ function buildDescriptiveFilename(metadata, originalFilename, index) {
   return parts.join('_') + ext;
 }
 
+// --- Output Organization: project dirs, JSON sidecars, dedup ---
+
+// Resolve the output directory with optional project organization.
+// When --project is set, creates: {baseOutput}/{project}/{type}/
+// Types: images, videos, lipsync, edits, pipeline, misc
+function resolveOutputDir(baseOutput, options = {}, type = 'misc') {
+  let dir = baseOutput;
+
+  if (options.project) {
+    // Sanitize project name for filesystem
+    const projectSlug = options.project
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-|-$/g, '');
+    dir = join(baseOutput, projectSlug, type);
+  }
+
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+// Infer the output type from the command/context
+function inferOutputType(command, options = {}) {
+  const typeMap = {
+    image: 'images',
+    video: 'videos',
+    lipsync: 'lipsync',
+    pipeline: 'pipeline',
+    'seed-bracket': 'seed-brackets',
+    edit: 'edits',
+    inpaint: 'edits',
+    upscale: 'upscaled',
+    'cinema-studio': 'cinema',
+    'motion-control': 'videos',
+    'video-edit': 'videos',
+    storyboard: 'storyboards',
+    'vibe-motion': 'videos',
+    influencer: 'characters',
+    character: 'characters',
+    app: 'apps',
+    chain: 'chained',
+    'mixed-media': 'mixed-media',
+    'motion-preset': 'motion-presets',
+    feature: 'features',
+    download: options.model === 'video' ? 'videos' : 'images',
+  };
+  return typeMap[command] || 'misc';
+}
+
+// Write a JSON sidecar metadata file alongside a downloaded file.
+// Sidecar path: {filePath}.json (e.g., hf_soul_2k_sunset_20260210.png.json)
+function writeJsonSidecar(filePath, metadata, options = {}) {
+  if (options.noSidecar) return;
+
+  const sidecarPath = `${filePath}.json`;
+  const sidecar = {
+    source: 'higgsfield-ui-automator',
+    version: '1.0',
+    timestamp: new Date().toISOString(),
+    file: basename(filePath),
+    ...metadata,
+  };
+
+  // Add file stats if the file exists
+  if (existsSync(filePath)) {
+    const stats = statSync(filePath);
+    sidecar.fileSize = stats.size;
+    sidecar.fileSizeHuman = stats.size > 1024 * 1024
+      ? `${(stats.size / 1024 / 1024).toFixed(1)}MB`
+      : `${(stats.size / 1024).toFixed(1)}KB`;
+  }
+
+  try {
+    writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
+  } catch (err) {
+    console.log(`[sidecar] Warning: could not write ${sidecarPath}: ${err.message}`);
+  }
+}
+
+// Compute SHA-256 hash of a file for deduplication
+function computeFileHash(filePath) {
+  try {
+    const data = readFileSync(filePath);
+    return createHash('sha256').update(data).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+// Check if a file is a duplicate of any existing file in the output directory.
+// Uses SHA-256 hash comparison. Returns the path of the duplicate if found, null otherwise.
+// Maintains a hash index file (.dedup-index.json) in the output directory for fast lookups.
+function checkDuplicate(filePath, outputDir, options = {}) {
+  if (options.noDedup) return null;
+
+  const hash = computeFileHash(filePath);
+  if (!hash) return null;
+
+  const indexPath = join(outputDir, '.dedup-index.json');
+  let index = {};
+
+  // Load existing index
+  if (existsSync(indexPath)) {
+    try {
+      index = JSON.parse(readFileSync(indexPath, 'utf-8'));
+    } catch { index = {}; }
+  }
+
+  // Check for duplicate
+  if (index[hash] && index[hash] !== basename(filePath)) {
+    const existingPath = join(outputDir, index[hash]);
+    if (existsSync(existingPath)) {
+      return existingPath;
+    }
+    // Stale entry — remove it
+    delete index[hash];
+  }
+
+  // Register this file in the index
+  index[hash] = basename(filePath);
+  try {
+    writeFileSync(indexPath, JSON.stringify(index, null, 2));
+  } catch { /* ignore write errors */ }
+
+  return null;
+}
+
+// Wrapper: save a downloaded file with sidecar + dedup.
+// Returns { path, duplicate, skipped } where duplicate is the existing file path if skipped.
+function finalizeDownload(filePath, metadata, outputDir, options = {}) {
+  // Check for duplicates
+  const duplicate = checkDuplicate(filePath, outputDir, options);
+  if (duplicate) {
+    console.log(`[dedup] Skipping duplicate: ${basename(filePath)} matches ${basename(duplicate)}`);
+    // Remove the duplicate file we just downloaded
+    try { unlinkSync(filePath); } catch { /* ignore */ }
+    return { path: duplicate, duplicate: true, skipped: true };
+  }
+
+  // Write JSON sidecar
+  writeJsonSidecar(filePath, metadata, options);
+
+  return { path: filePath, duplicate: false, skipped: false };
+}
+
 // Download generated results from the current page
 // Strategy: click each generated image to open the "Asset showcase" dialog,
 // then click the Download button in the dialog. Falls back to extracting
 // CloudFront CDN URLs directly from img[alt="image generation"] elements.
-async function downloadLatestResult(page, outputDir, downloadAll = true) {
+async function downloadLatestResult(page, outputDir, downloadAll = true, options = {}) {
   const downloaded = [];
 
   try {
@@ -2284,8 +2451,14 @@ async function downloadLatestResult(page, outputDir, downloadAll = true) {
                 const descriptiveName = buildDescriptiveFilename(metadata, origFilename, i);
                 const savePath = join(outputDir, descriptiveName);
                 await download.saveAs(savePath);
-                console.log(`Downloaded [${i + 1}/${toDownload}]: ${savePath}`);
-                downloaded.push(savePath);
+                const result = finalizeDownload(savePath, {
+                  command: 'download', type: 'image', ...metadata,
+                  originalFilename: origFilename,
+                }, outputDir, options);
+                if (!result.skipped) {
+                  console.log(`Downloaded [${i + 1}/${toDownload}]: ${savePath}`);
+                }
+                downloaded.push(result.path);
               } else {
                 // Download event didn't fire - the button may trigger a blob/fetch download
                 // Wait a moment and check if a file appeared
@@ -2346,13 +2519,20 @@ async function downloadLatestResult(page, outputDir, downloadAll = true) {
         const url = toDownload[i];
         const isVideo = url.includes('.mp4') || url.includes('video');
         const ext = isVideo ? '.mp4' : '.webp';
-        const filename = `higgsfield-${Date.now()}-${i}${ext}`;
+        const cdnMeta = { promptSnippet: 'cdn-fallback' };
+        const filename = buildDescriptiveFilename(cdnMeta, `higgsfield-cdn-${Date.now()}${ext}`, i);
         const savePath = join(outputDir, filename);
 
         try {
           execSync(`curl -sL -o "${savePath}" "${url}"`, { timeout: 60000 });
-          console.log(`Downloaded via CDN [${i + 1}/${toDownload.length}]: ${savePath}`);
-          downloaded.push(savePath);
+          const result = finalizeDownload(savePath, {
+            command: 'download', type: isVideo ? 'video' : 'image',
+            cdnUrl: url, strategy: 'cdn-fallback',
+          }, outputDir, options);
+          if (!result.skipped) {
+            console.log(`Downloaded via CDN [${i + 1}/${toDownload.length}]: ${savePath}`);
+          }
+          downloaded.push(result.path);
         } catch (curlErr) {
           console.log(`CDN download failed for ${url}: ${curlErr.message}`);
         }
@@ -2375,7 +2555,7 @@ async function downloadLatestResult(page, outputDir, downloadAll = true) {
 
 // Download specific images by their index on the page
 // Uses the same dialog-based approach as downloadLatestResult but only for specified indices
-async function downloadSpecificImages(page, outputDir, indices) {
+async function downloadSpecificImages(page, outputDir, indices, options = {}) {
   const downloaded = [];
   const generatedImgs = page.locator('img[alt="image generation"], img[alt*="media asset by id"]');
 
@@ -2402,8 +2582,14 @@ async function downloadSpecificImages(page, outputDir, indices) {
             const descriptiveName = buildDescriptiveFilename(metadata, origFilename, downloaded.length);
             const savePath = join(outputDir, descriptiveName);
             await download.saveAs(savePath);
-            console.log(`Downloaded [${downloaded.length + 1}/${indices.length}]: ${savePath}`);
-            downloaded.push(savePath);
+            const result = finalizeDownload(savePath, {
+              command: 'image', type: 'image', ...metadata,
+              originalFilename: origFilename, imageIndex: idx,
+            }, outputDir, options);
+            if (!result.skipped) {
+              console.log(`Downloaded [${downloaded.length + 1}/${indices.length}]: ${savePath}`);
+            }
+            downloaded.push(result.path);
           }
         }
 
@@ -2443,12 +2629,19 @@ async function downloadSpecificImages(page, outputDir, indices) {
 
     for (let i = 0; i < cdnUrls.length; i++) {
       const ext = cdnUrls[i].includes('.mp4') ? '.mp4' : '.webp';
-      const filename = `higgsfield-${Date.now()}-cdn-${i}${ext}`;
+      const cdnMeta = { promptSnippet: 'cdn-fallback' };
+      const filename = buildDescriptiveFilename(cdnMeta, `higgsfield-cdn-${Date.now()}${ext}`, downloaded.length);
       const savePath = join(outputDir, filename);
       try {
         execSync(`curl -sL -o "${savePath}" "${cdnUrls[i]}"`, { timeout: 60000 });
-        console.log(`Downloaded via CDN [${downloaded.length + 1}]: ${savePath}`);
-        downloaded.push(savePath);
+        const result = finalizeDownload(savePath, {
+          command: 'image', type: 'image', cdnUrl: cdnUrls[i],
+          strategy: 'cdn-fallback', imageIndex: indices[downloaded.length],
+        }, outputDir, options);
+        if (!result.skipped) {
+          console.log(`Downloaded via CDN [${downloaded.length + 1}]: ${savePath}`);
+        }
+        downloaded.push(result.path);
       } catch (curlErr) {
         console.log(`CDN download failed: ${curlErr.message}`);
       }
@@ -2518,7 +2711,9 @@ async function useApp(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, `app-${appSlug}-result.png`), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'apps');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -3045,6 +3240,12 @@ async function pollAndDownloadVideos(page, submittedJobs, outputDir, timeout = 6
                 const httpCode = curlResult.trim();
                 if (httpCode === '200' && existsSync(savePath) && statSync(savePath).size > 10000) {
                   const fileSize = statSync(savePath).size;
+                  // Write JSON sidecar for pipeline scene video
+                  writeJsonSidecar(savePath, {
+                    command: 'pipeline', type: 'video', ...meta,
+                    sceneIndex: job.sceneIndex, strategy: 'api-interception',
+                    cloudFrontUrl: videoUrl, matchScore: bestScore,
+                  });
                   console.log(`  Scene ${job.sceneIndex + 1}: downloaded (${(fileSize / 1024 / 1024).toFixed(1)}MB) ${filename}`);
                   console.log(`    Matched prompt (${bestScore} chars): "${bestMatch.prompt?.substring(0, 60)}..."`);
                   results.set(job.sceneIndex, savePath);
@@ -3536,7 +3737,9 @@ async function cinemaStudio(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'cinema-studio-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'cinema');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -3635,7 +3838,9 @@ async function motionControl(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'motion-control-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadVideoFromHistory(page, options.output || DOWNLOAD_DIR);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'videos');
+      await downloadVideoFromHistory(page, outputDir, {}, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -3715,7 +3920,9 @@ async function editImage(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, `edit-${model}-result.png`), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'edits');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -3773,7 +3980,9 @@ async function upscale(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'upscale-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'upscaled');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -3838,7 +4047,9 @@ async function manageAssets(options = {}) {
         await page.screenshot({ path: join(STATE_DIR, 'asset-detail.png'), fullPage: false });
 
         // Try to download via the asset detail view
-        await downloadLatestResult(page, options.output || DOWNLOAD_DIR, false);
+        const baseOutput = options.output || DOWNLOAD_DIR;
+        const dlDir = resolveOutputDir(baseOutput, options, 'misc');
+        await downloadLatestResult(page, dlDir, false, options);
         console.log('Asset downloaded');
       }
     }
@@ -3846,7 +4057,8 @@ async function manageAssets(options = {}) {
     if (action === 'download-all') {
       // Download multiple assets
       const maxDownloads = options.limit || 10;
-      const outputDir = options.output || DOWNLOAD_DIR;
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const dlDir = resolveOutputDir(baseOutput, options, 'misc');
       console.log(`Downloading up to ${maxDownloads} assets...`);
 
       for (let i = 0; i < Math.min(maxDownloads, assetCount); i++) {
@@ -3854,7 +4066,7 @@ async function manageAssets(options = {}) {
         if (await assetImg.isVisible({ timeout: 2000 }).catch(() => false)) {
           await assetImg.click();
           await page.waitForTimeout(2000);
-          await downloadLatestResult(page, outputDir, false);
+          await downloadLatestResult(page, dlDir, false, options);
           await page.keyboard.press('Escape');
           await page.waitForTimeout(500);
           console.log(`Downloaded asset ${i + 1}/${maxDownloads}`);
@@ -4047,7 +4259,7 @@ async function assetChain(options = {}) {
 
       // Download the asset from the dialog first
       const outputDir = options.output || DOWNLOAD_DIR;
-      const downloadedFiles = await downloadLatestResult(page, outputDir, false);
+      const downloadedFiles = await downloadLatestResult(page, outputDir, false, options);
       const downloadedFile = Array.isArray(downloadedFiles) ? downloadedFiles[0] : downloadedFiles;
 
       // Close dialog
@@ -4192,13 +4404,14 @@ async function assetChain(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, `asset-chain-${action}-result.png`), fullPage: false });
 
     if (options.wait !== false) {
-      const outputDir = options.output || DOWNLOAD_DIR;
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'chained');
       const isVideoAction = ['animate'].includes(action);
       if (isVideoAction) {
-        await downloadVideoFromHistory(page, outputDir);
+        await downloadVideoFromHistory(page, outputDir, {}, options);
       } else {
         // Try standard download first
-        const downloaded = await downloadLatestResult(page, outputDir, true);
+        const downloaded = await downloadLatestResult(page, outputDir, true, options);
         const hasDownloaded = Array.isArray(downloaded) ? downloaded.length > 0 : !!downloaded;
 
         // If standard download failed, try the download icon button (upscale/edit pages use icon buttons)
@@ -4354,7 +4567,9 @@ async function mixedMediaPreset(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, `mixed-media-${presetKey}-result.png`), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'mixed-media');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4477,7 +4692,9 @@ async function motionPreset(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'motion-preset-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadVideoFromHistory(page, options.output || DOWNLOAD_DIR);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'motion-presets');
+      await downloadVideoFromHistory(page, outputDir, {}, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4567,7 +4784,9 @@ async function editVideo(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'video-edit-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadVideoFromHistory(page, options.output || DOWNLOAD_DIR);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'videos');
+      await downloadVideoFromHistory(page, outputDir, {}, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4652,7 +4871,9 @@ async function storyboard(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'storyboard-result.png'), fullPage: true });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'storyboards');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4768,7 +4989,9 @@ async function vibeMotion(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'vibe-motion-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadVideoFromHistory(page, options.output || DOWNLOAD_DIR);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'videos');
+      await downloadVideoFromHistory(page, outputDir, {}, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4843,7 +5066,9 @@ async function aiInfluencer(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'ai-influencer-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'characters');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -4914,7 +5139,9 @@ async function createCharacter(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, 'character-result.png'), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'characters');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -5026,7 +5253,9 @@ async function featurePage(options = {}) {
     await page.screenshot({ path: join(STATE_DIR, `feature-${featureKey}-result.png`), fullPage: false });
 
     if (options.wait !== false) {
-      await downloadLatestResult(page, options.output || DOWNLOAD_DIR, true);
+      const baseOutput = options.output || DOWNLOAD_DIR;
+      const outputDir = resolveOutputDir(baseOutput, options, 'features');
+      await downloadLatestResult(page, outputDir, true, options);
     }
 
     await context.storageState({ path: STATE_FILE });
@@ -5118,6 +5347,9 @@ Options:
   --chain-action     Asset chain action: animate, inpaint, upscale, relight, angles, shots, ai-stylist, skin-enhancer, multishot
   --feature          Feature page slug: fashion-factory, ugc-factory, photodump-studio, camera-controls, effects
   --subtype          Vibe Motion sub-type: infographics, text-animation, posters, presentation, from-scratch
+  --project          Project name for organized output dirs (creates {output}/{project}/{type}/)
+  --no-sidecar       Disable JSON sidecar metadata files
+  --no-dedup         Disable SHA-256 duplicate detection
   --force            Override credit guard (proceed even with low credits)
   --dry-run          Navigate and configure but don't click Generate
   --no-retry         Disable automatic retry on failure
@@ -5221,7 +5453,9 @@ Examples:
         await dlPage.goto(`${BASE_URL}/create/video`, { waitUntil: 'domcontentloaded', timeout: 60000 });
         await dlPage.waitForTimeout(5000);
         await dismissAllModals(dlPage);
-        await downloadVideoFromHistory(dlPage, options.output || DOWNLOAD_DIR);
+        const baseOutput = options.output || DOWNLOAD_DIR;
+        const dlDir = resolveOutputDir(baseOutput, options, 'videos');
+        await downloadVideoFromHistory(dlPage, dlDir, {}, options);
       } else {
         // Download latest image from image page
         const dlUrl = `${BASE_URL}/image/${dlModel}`;
@@ -5229,7 +5463,9 @@ Examples:
         await dlPage.goto(dlUrl, { waitUntil: 'domcontentloaded', timeout: 60000 });
         await dlPage.waitForTimeout(5000);
         await dismissAllModals(dlPage);
-        await downloadLatestResult(dlPage, options.output || DOWNLOAD_DIR, true);
+        const baseOutput = options.output || DOWNLOAD_DIR;
+        const dlDir = resolveOutputDir(baseOutput, options, 'images');
+        await downloadLatestResult(dlPage, dlDir, true, options);
       }
 
       await dlCtx.storageState({ path: STATE_FILE });
diff --git a/.agents/tools/video/higgsfield-ui.md b/.agents/tools/video/higgsfield-ui.md
index 128347cd0..27933bb64 100644
--- a/.agents/tools/video/higgsfield-ui.md
+++ b/.agents/tools/video/higgsfield-ui.md
@@ -78,7 +78,10 @@ higgsfield-helper.sh (shell wrapper)
         ├── Persistent auth state (~/.aidevops/.agent-workspace/work/higgsfield/auth-state.json)
         ├── Site discovery cache (~/.aidevops/.agent-workspace/work/higgsfield/routes-cache.json)
         ├── Credentials from ~/.config/aidevops/credentials.sh
-        └── Downloads to ~/Downloads/ (descriptive filenames: hf_{model}_{quality}_{prompt}_{ts}.ext)
+        ├── Downloads to ~/Downloads/ (descriptive filenames: hf_{model}_{quality}_{prompt}_{ts}.ext)
+        ├── JSON sidecar metadata (.json alongside each download)
+        ├── SHA-256 dedup index (.dedup-index.json per output dir)
+        └── Project dirs via --project (organized by type: images/, videos/, etc.)
 ```
 
 **Why Playwright direct?** Fastest browser automation (0.9s form fill), full API control, headless/headed modes, persistent auth via `storageState`. No wrapper overhead.
@@ -546,7 +549,43 @@ Use `--unlimited` flag to restrict to unlimited models only.
 
 **Unlimited model routing**: Models with "365" subscriptions use dedicated feature pages (e.g., `/nano-banana-pro`, `/seedream-4-5`) that have an "Unlimited" toggle switch. The automator automatically navigates to these pages and enables the switch. Standard `/image/` routes cost credits even for subscribed models.
 
-## Download Filenames
+## Output Organization
+
+### Project Directories
+
+Use `--project` to organize outputs into structured directories:
+
+```bash
+# Without --project: files go to ~/Downloads/ (flat)
+higgsfield-helper.sh image "A sunset" --output ~/Downloads/
+
+# With --project: files go to ~/Downloads/my-video/images/
+higgsfield-helper.sh image "A sunset" --output ~/Downloads/ --project my-video
+```
+
+Directory structure with `--project`:
+
+```text
+{output}/{project}/
+├── images/          # Image generations
+├── videos/          # Video generations
+├── lipsync/         # Lipsync outputs
+├── edits/           # Edit/inpaint results
+├── upscaled/        # Upscaled media
+├── cinema/          # Cinema Studio outputs
+├── storyboards/     # Storyboard panels
+├── characters/      # Character/influencer outputs
+├── apps/            # App/effect results
+├── chained/         # Asset chain outputs
+├── mixed-media/     # Mixed media preset results
+├── motion-presets/  # Motion/VFX preset results
+├── features/        # Feature page outputs
+├── seed-brackets/   # Seed bracketing results
+├── pipeline/        # Pipeline outputs
+└── misc/            # Other downloads
+```
+
+### Descriptive Filenames
 
 All downloads use descriptive filenames:
 
@@ -558,6 +597,43 @@ Example: `hf_higgsfield-soul_2k_sunset-beach_a-serene-mountain-landscape_2026020
 
 Metadata is extracted from the Asset showcase dialog before downloading.
 
+### JSON Sidecar Metadata
+
+Every downloaded file gets a companion `.json` sidecar with full metadata:
+
+```bash
+ls ~/Downloads/my-video/images/
+# hf_soul_2k_a-serene-mountain-landscape_20260210120000_1.png
+# hf_soul_2k_a-serene-mountain-landscape_20260210120000_1.png.json
+```
+
+Sidecar contents:
+
+```json
+{
+  "source": "higgsfield-ui-automator",
+  "version": "1.0",
+  "timestamp": "2026-02-10T12:00:00.000Z",
+  "file": "hf_soul_2k_a-serene-mountain-landscape_20260210120000_1.png",
+  "command": "image",
+  "type": "image",
+  "model": "Higgsfield Soul",
+  "quality": "2k",
+  "preset": "General",
+  "promptSnippet": "A serene mountain landscape at golden hour, photorealistic",
+  "fileSize": 2456789,
+  "fileSizeHuman": "2.3MB"
+}
+```
+
+Disable with `--no-sidecar`.
+
+### Deduplication
+
+SHA-256 hash-based deduplication prevents downloading the same file twice. A `.dedup-index.json` file in each output directory tracks file hashes. Duplicate downloads are automatically skipped.
+
+Disable with `--no-dedup`.
+
 ## Production Pipeline
 
 The `pipeline` command chains image generation, video animation, lipsync, and ffmpeg assembly into a single workflow. Video generation uses **parallel submission** -- all scene videos are submitted to Higgsfield at once, then polled simultaneously, cutting total time from N*4min to ~4min regardless of scene count.
@@ -743,6 +819,9 @@ Results saved to `~/Downloads/seed-bracket-{timestamp}/` with `bracket-results.j
 --chain-action     Asset chain action: animate, inpaint, upscale, relight, angles, shots, ai-stylist, skin-enhancer, multishot
 --feature          Feature page slug: fashion-factory, ugc-factory, photodump-studio, camera-controls, effects
 --subtype          Vibe Motion sub-type: infographics, text-animation, posters, presentation, from-scratch
+--project          Project name for organized output dirs ({output}/{project}/{type}/)
+--no-sidecar       Disable JSON sidecar metadata files
+--no-dedup         Disable SHA-256 duplicate detection
 ```
 
 ## Prompt Engineering Tips