@dboio/cli 0.6.14 → 0.8.0

package/src/commands/clone.js

@@ -2,11 +2,11 @@ import { Command } from 'commander';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { join, basename, extname } from 'path';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset } from '../lib/config.js';
-import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement } from '../lib/config.js';
+import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES, EXTENSION_DESCRIPTORS_DIR, EXTENSION_UNSUPPORTED_DIR, DOCUMENTATION_DIR, buildDescriptorMapping, saveDescriptorMapping, loadDescriptorMapping, resolveExtensionSubDir } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
-import { setFileTimestamps } from '../lib/timestamps.js';
-import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge } from '../lib/diff.js';
+import { setFileTimestamps, parseServerDate } from '../lib/timestamps.js';
+import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge, isDiffable } from '../lib/diff.js';
 import { checkDomainChange } from '../lib/domain-guard.js';
 
 /**
@@ -421,6 +421,10 @@ export const cloneCommand = new Command('clone')
   .description('Clone an app from DBO.io to a local project structure')
   .argument('[source]', 'Local JSON file path (optional)')
   .option('--app <shortName>', 'App short name to fetch from server')
+  .option('-e, --entity <type>', 'Only clone a specific entity type (e.g. output, content, media, extension)')
+  .option('--documentation-only', 'When used with -e extension, clone only documentation extensions')
+  .option('--descriptor-types <bool>', 'Sort extensions into descriptor sub-directories (default: true)', 'true')
+  .option('--force', 'Force re-processing of all files, skip change detection')
   .option('--domain <host>', 'Override domain')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('-v, --verbose', 'Show HTTP request details')
@@ -434,26 +438,46 @@ export const cloneCommand = new Command('clone')
   });
 
 /**
- * Main clone workflow. Exported for use by init --clone.
+ * Resolve app JSON from a given source (file path, URL, or server fetch).
+ * Throws on failure so the caller can retry with a different source.
  */
-export async function performClone(source, options = {}) {
-  const config = await loadConfig();
-  const effectiveDomain = options.domain || config.domain;
-  let appJson;
-
-  // Step 1: Load the app JSON
+async function resolveAppSource(source, options, config) {
   if (source) {
-    // Local file
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+      log.info(`Fetching app JSON from ${source}...`);
+      const res = await fetch(source);
+      if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${source}`);
+      return await res.json();
+    }
     log.info(`Loading app JSON from ${source}...`);
     const raw = await readFile(source, 'utf8');
-    appJson = JSON.parse(raw);
+    return JSON.parse(raw);
   } else if (options.app) {
-    // Fetch from server by AppShortName
-    appJson = await fetchAppFromServer(options.app, options, config);
-  } else if (config.AppShortName) {
-    // Use config's AppShortName
-    appJson = await fetchAppFromServer(config.AppShortName, options, config);
+    return await fetchAppFromServer(options.app, options, config);
   } else {
+    // Try stored cloneSource before falling back to server fetch
+    const storedSource = await loadCloneSource();
+    if (storedSource && storedSource !== 'default') {
+      // Stored source is a local file path or URL — reuse it
+      if (storedSource.startsWith('http://') || storedSource.startsWith('https://')) {
+        log.info(`Fetching app JSON from ${storedSource} (stored source)...`);
+        const res = await fetch(storedSource);
+        if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${storedSource}`);
+        return await res.json();
+      }
+      if (await fileExists(storedSource)) {
+        log.info(`Loading app JSON from ${storedSource} (stored source)...`);
+        const raw = await readFile(storedSource, 'utf8');
+        return JSON.parse(raw);
+      }
+      // Stored file no longer exists — fall through to server fetch
+      log.dim(`  Stored clone source "${storedSource}" not found, trying server...`);
+    }
+
+    if (config.AppShortName) {
+      return await fetchAppFromServer(config.AppShortName, options, config);
+    }
+
     // Prompt
     const inquirer = (await import('inquirer')).default;
     const { choice } = await inquirer.prompt([{
@@ -472,7 +496,7 @@ export async function performClone(source, options = {}) {
         message: 'App short name:',
         validate: v => v.trim() ? true : 'App short name is required',
       }]);
-      appJson = await fetchAppFromServer(appName, options, config);
+      return await fetchAppFromServer(appName, options, config);
     } else {
       const { filePath } = await inquirer.prompt([{
         type: 'input', name: 'filePath',
@@ -480,7 +504,155 @@ export async function performClone(source, options = {}) {
         validate: v => v.trim() ? true : 'File path is required',
       }]);
       const raw = await readFile(filePath, 'utf8');
-      appJson = JSON.parse(raw);
+      return JSON.parse(raw);
+    }
+  }
+}
+
+/**
+ * Check synchronize.json for un-pushed staged items before cloning.
+ * Warns the user and offers options: push first, review individually, ignore, or clear.
+ */
+async function checkPendingSynchronize(options) {
+  const sync = await loadSynchronize();
+  const deleteCount = (sync.delete || []).length;
+  const editCount = (sync.edit || []).length;
+  const addCount = (sync.add || []).length;
+  const totalCount = deleteCount + editCount + addCount;
+
+  if (totalCount === 0) return;
+
+  log.warn('');
+  log.warn(`  ⚠  There are ${totalCount} un-pushed staged item(s) in .dbo/synchronize.json:`);
+  if (deleteCount > 0) log.warn(`     ${deleteCount} pending deletion(s)`);
+  if (editCount > 0) log.warn(`     ${editCount} pending edit(s)`);
+  if (addCount > 0) log.warn(`     ${addCount} pending add(s)`);
+  log.warn('');
+
+  if (options.yes) {
+    log.dim('  Ignoring staged items (-y flag)');
+    return;
+  }
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'How would you like to handle the staged items?',
+    choices: [
+      { name: 'Ignore — keep staged items and continue cloning', value: 'ignore' },
+      { name: 'Review — show each item and decide individually', value: 'review' },
+      { name: 'Clear — discard all staged items and continue cloning', value: 'clear' },
+      { name: 'Abort — stop cloning so you can push first', value: 'abort' },
+    ],
+  }]);
+
+  if (action === 'abort') {
+    log.info('Clone aborted. Run "dbo push" to process staged items first.');
+    process.exit(0);
+  }
+
+  if (action === 'clear') {
+    await saveSynchronize({ delete: [], edit: [], add: [] });
+    log.success('Cleared all staged items from synchronize.json');
+    return;
+  }
+
+  if (action === 'review') {
+    const kept = { delete: [], edit: [], add: [] };
+
+    for (const category of ['delete', 'edit', 'add']) {
+      const items = sync[category] || [];
+      if (items.length === 0) continue;
+
+      for (const item of items) {
+        const label = item.Name || item.UID || item.metaPath || JSON.stringify(item).substring(0, 80);
+        const entity = item._entity || item.entity || '';
+        const desc = entity ? `[${category}] ${entity}: ${label}` : `[${category}] ${label}`;
+
+        const { keep } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'keep',
+          message: `Keep staged? ${desc}`,
+          default: true,
+        }]);
+
+        if (keep) {
+          kept[category].push(item);
+        } else {
+          log.dim(`  Discarded: ${desc}`);
+        }
+      }
+    }
+
+    await saveSynchronize(kept);
+    const remaining = kept.delete.length + kept.edit.length + kept.add.length;
+    if (remaining > 0) {
+      log.info(`${remaining} staged item(s) kept`);
+    } else {
+      log.success('All staged items discarded');
+    }
+    return;
+  }
+
+  // action === 'ignore' — do nothing, keep staged items
+  log.dim('  Keeping staged items');
+}
+
+/**
+ * Main clone workflow. Exported for use by init --clone.
+ */
+export async function performClone(source, options = {}) {
+  const config = await loadConfig();
+  const effectiveDomain = options.domain || config.domain;
+  let appJson;
+
+  // Step 1: Source mismatch detection
+  // Warn when the user provides an explicit source that differs from the stored one.
+  const storedCloneSource = await loadCloneSource();
+  if (source && storedCloneSource && source !== storedCloneSource) {
+    if (!options.force && !options.yes) {
+      log.warn('');
+      log.warn(`  ⚠  This project was previously cloned from: ${storedCloneSource}`);
+      log.warn(`     Requested source:                        ${source}`);
+      const inquirer = (await import('inquirer')).default;
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: 'Clone from the new source anyway? This will update the stored clone source.',
+        default: false,
+      }]);
+      if (!confirmed) {
+        log.info('Clone aborted.');
+        return;
+      }
+    } else {
+      log.warn(`  ⚠  Clone source override: "${storedCloneSource}" → "${source}"`);
+    }
+  }
+
+  // Step 2: Load the app JSON — retry loop with fallback prompt on failure
+  let activeSource = source;
+  while (true) {
+    try {
+      appJson = await resolveAppSource(activeSource, options, config);
+      break;
+    } catch (err) {
+      if (options.yes || !process.stdin.isTTY) {
+        throw err;
+      }
+      log.warn('');
+      log.warn(`  ⚠  Source did not return expected results: ${err.message}`);
+      const inquirer = (await import('inquirer')).default;
+      const { fallback } = await inquirer.prompt([{
+        type: 'input',
+        name: 'fallback',
+        message: 'Enter another local file path or URL to retry (or leave empty to abort):',
+      }]);
+      if (!fallback || !fallback.trim()) {
+        throw new Error('Clone aborted: no valid source provided.');
+      }
+      activeSource = fallback.trim();
     }
   }
 
@@ -500,6 +672,9 @@ export async function performClone(source, options = {}) {
 
   log.success(`Cloning "${appJson.Name}" (${appJson.ShortName})`);
 
+  // Check for un-pushed staged items in synchronize.json
+  await checkPendingSynchronize(options);
+
   // Ensure sensitive files are gitignored
   await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt']);
 
@@ -510,6 +685,7 @@ export async function performClone(source, options = {}) {
     AppName: appJson.Name,
     AppShortName: appJson.ShortName,
   });
+  await saveCloneSource(activeSource || 'default');
   log.dim('  Updated .dbo/config.json with app metadata');
 
   // Detect and store ModifyKey for locked/production apps
@@ -573,39 +749,75 @@ export async function performClone(source, options = {}) {
     log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
   }
 
-  // Step 4c: Detect and resolve file path collisions
-  log.info('Scanning for file path collisions...');
-  const fileRegistry = await buildFileRegistry(appJson, structure, placementPrefs);
-  const toDeleteUIDs = await resolveCollisions(fileRegistry, options);
+  // Resolve --entity filter: which entity types to process
+  // "output" expands to all OUTPUT_HIERARCHY_ENTITIES, others are matched directly
+  const entityFilter = resolveEntityFilter(options.entity);
+  if (entityFilter) {
+    log.info(`Entity filter: only processing ${options.entity}`);
+  }
+
+  // Step 4c: Detect and resolve file path collisions (skip in entity-filter mode)
+  let toDeleteUIDs = new Set();
+  if (!entityFilter) {
+    log.info('Scanning for file path collisions...');
+    const fileRegistry = await buildFileRegistry(appJson, structure, placementPrefs);
+    toDeleteUIDs = await resolveCollisions(fileRegistry, options);
 
-  if (toDeleteUIDs.size > 0) {
-    await stageCollisionDeletions(toDeleteUIDs, appJson, options);
+    if (toDeleteUIDs.size > 0) {
+      await stageCollisionDeletions(toDeleteUIDs, appJson, options);
+    }
   }
 
   // Step 5: Process content → files + metadata (skip rejected records)
-  const contentRefs = await processContentEntries(
-    appJson.children.content || [],
-    structure,
-    options,
-    placementPrefs.contentPlacement,
-    serverTz,
-    toDeleteUIDs,
-  );
+  let contentRefs = [];
+  if (!entityFilter || entityFilter.has('content')) {
+    contentRefs = await processContentEntries(
+      appJson.children.content || [],
+      structure,
+      options,
+      placementPrefs.contentPlacement,
+      serverTz,
+      toDeleteUIDs,
+    );
+  }
 
   // Step 5b: Process media → download binary files + metadata (skip rejected records)
   let mediaRefs = [];
-  const mediaEntries = appJson.children.media || [];
-  if (mediaEntries.length > 0) {
-    mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
+  if (!entityFilter || entityFilter.has('media')) {
+    const mediaEntries = appJson.children.media || [];
+    if (mediaEntries.length > 0) {
+      mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
+    }
   }
 
-  // Step 6: Process other entities (not output, not bin, not content, not media)
+  // Step 5c: Process output hierarchy
   const otherRefs = {};
+  if (!entityFilter || entityFilter.has('output')) {
+    const outputEntries = appJson.children.output || [];
+    if (outputEntries.length > 0) {
+      const outputRefs = await processOutputHierarchy(appJson, structure, options, serverTz);
+      if (outputRefs.length > 0) {
+        otherRefs.output = outputRefs;
+      }
+    }
+  }
+
+  // Step 6: Process other entities (not output hierarchy, not bin, not content, not media)
   for (const [entityName, entries] of Object.entries(appJson.children)) {
-    if (['bin', 'content', 'output', 'media'].includes(entityName)) continue;
+    if (['bin', 'content', 'output', 'output_value', 'output_value_filter',
+         'output_value_entity_column_rel', 'media'].includes(entityName)) continue;
     if (!Array.isArray(entries)) continue;
 
-    if (ENTITY_DIR_MAP[entityName]) {
+    // Skip if entity filter is active and this entity doesn't match
+    if (entityFilter && !entityFilter.has(entityName)) continue;
+
+    if (entityName === 'extension') {
+      // Extension entities: descriptor-organized sub-directories
+      const refs = await processExtensionEntries(entries, structure, options, serverTz);
+      if (refs.length > 0) {
+        otherRefs[entityName] = refs;
+      }
+    } else if (ENTITY_DIR_MAP[entityName]) {
       // Entity types with project directories — process into their directory
       const refs = await processEntityDirEntries(entityName, entries, options, serverTz);
       if (refs.length > 0) {
@@ -628,18 +840,43 @@ export async function performClone(source, options = {}) {
   // Step 7: Save app.json with references
   await saveAppJson(appJson, contentRefs, otherRefs, effectiveDomain);
 
-  // Step 8: Create .app.json baseline for delta tracking
-  await saveBaselineFile(appJson);
+  // Step 8: Create .app.json baseline for delta tracking (skip in entity-filter mode to avoid overwriting)
+  if (!entityFilter) {
+    await saveBaselineFile(appJson);
+  }
 
   // Step 9: Ensure .app.json is in .gitignore
   await ensureGitignore(['.app.json']);
 
   log.plain('');
-  log.success('Clone complete!');
+  log.success(entityFilter ? `Clone complete! (filtered: ${options.entity})` : 'Clone complete!');
   log.dim('  app.json saved to project root');
   log.dim('  Run "dbo login" to authenticate, then "dbo push" to deploy changes');
 }
 
+/**
+ * Resolve --entity filter into a Set of entity keys to process.
+ * Returns null if no filter (process everything), or a Set of entity key strings.
+ *
+ * "output" expands to all OUTPUT_HIERARCHY_ENTITIES.
+ * Entity-dir names (e.g. "extension", "site") are matched directly.
+ * Documentation aliases are also accepted (e.g. "column" → "output_value").
+ */
+function resolveEntityFilter(entityArg) {
+  if (!entityArg) return null;
+
+  const input = entityArg.toLowerCase().trim();
+
+  // "output" or any output sub-entity → process all output hierarchy entities
+  const docToPhysical = { column: 'output_value', filter: 'output_value_filter', join: 'output_value_entity_column_rel' };
+  if (input === 'output' || OUTPUT_HIERARCHY_ENTITIES.includes(input) || docToPhysical[input]) {
+    return new Set(OUTPUT_HIERARCHY_ENTITIES.concat(['output']));
+  }
+
+  // Direct match on known entity types
+  return new Set([input]);
+}
+
 /**
  * Resolve placement preferences from config or prompt the user.
  * Returns { contentPlacement, mediaPlacement } where values are 'path'|'bin'|'ask'|null
@@ -699,16 +936,23 @@ async function resolvePlacementPreferences(appJson, options) {
     const answers = await inquirer.prompt(prompts);
     contentPlacement = contentPlacement || answers.contentPlacement || 'bin';
     mediaPlacement = mediaPlacement || answers.mediaPlacement || 'bin';
+  }
+
+  // Resolve defaults for any still-unset values
+  contentPlacement = contentPlacement || 'bin';
+  mediaPlacement = mediaPlacement || 'bin';
 
-    // Save to config for future clones
-    await saveClonePlacement({ mediaPlacement, contentPlacement });
-    log.dim('  Saved placement preferences to .dbo/config.json');
+  // Always persist resolved values — not just when prompts were shown.
+  // This ensures defaults are saved even when the app has no content/media yet,
+  // so subsequent clones that do have records skip the prompts.
+  if (!saved.contentPlacement || !saved.mediaPlacement) {
+    await saveClonePlacement({ contentPlacement, mediaPlacement });
+    if (prompts.length > 0) {
+      log.dim('  Saved placement preferences to .dbo/config.json');
+    }
   }
 
-  return {
-    contentPlacement: contentPlacement || 'bin',
-    mediaPlacement: mediaPlacement || 'bin',
-  };
+  return { contentPlacement, mediaPlacement };
 }
 
 /**
@@ -718,10 +962,7 @@ async function fetchAppFromServer(appShortName, options, config) {
   const client = new DboClient({ domain: options.domain, verbose: options.verbose });
   log.info(`Fetching app "${appShortName}" from server...`);
 
-  const result = await client.get('/api/o/object_lookup_app__CALL', {
-    '_filter:AppShortName': appShortName,
-    '_format': 'json_raw',
-  });
+  const result = await client.get(`/api/app/object/${appShortName}`);
 
   const data = result.payload || result.data;
   const rows = Array.isArray(data) ? data : (data?.Rows || data?.rows || []);
@@ -1025,11 +1266,16 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       }
 
       if (bulkAction.value !== 'overwrite_all') {
+        const configWithTz = { ...config, ServerTimezone: serverTz };
         const localSyncTime = await getLocalSyncTime(metaPath);
-        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, config);
+        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+        const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
         if (serverNewer) {
-          const action = await promptChangeDetection(finalName, record, config);
+          const action = await promptChangeDetection(finalName, record, configWithTz, {
+            serverDate,
+            localDate: localSyncTime,
+          });
 
           if (action === 'skip') {
             log.dim(`  Skipped ${finalName}`);
@@ -1046,14 +1292,18 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
             bulkAction.value = 'overwrite_all';
           }
           if (action === 'compare') {
-            await inlineDiffAndMerge(record, metaPath, config);
+            await inlineDiffAndMerge(record, metaPath, configWithTz);
             refs.push({ uid: record.UID, metaPath });
             continue;
           }
         } else {
-          const locallyModified = await hasLocalModifications(metaPath, config);
+          const locallyModified = await hasLocalModifications(metaPath, configWithTz);
           if (locallyModified) {
-            const action = await promptChangeDetection(finalName, record, config, { localIsNewer: true });
+            const action = await promptChangeDetection(finalName, record, configWithTz, {
+              localIsNewer: true,
+              serverDate,
+              localDate: localSyncTime,
+            });
 
             if (action === 'skip') {
               log.dim(`  Kept local: ${finalName}`);
@@ -1070,7 +1320,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
               bulkAction.value = 'overwrite_all';
             }
             if (action === 'compare') {
-              await inlineDiffAndMerge(record, metaPath, config, { localIsNewer: true });
+              await inlineDiffAndMerge(record, metaPath, configWithTz, { localIsNewer: true });
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
@@ -1142,6 +1392,378 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
   return refs;
 }
 
+// ─── Extension Descriptor Sub-directory Processing ────────────────────────
+
+/**
+ * Scan extension records for descriptor_definition entries.
+ * Builds the mapping, persists to structure.json, always creates Extensions/Unsupported/,
+ * and creates sub-directories for every mapped descriptor.
+ * Returns the mapping object.
+ *
+ * @param {Object[]} extensionEntries
+ * @param {Object}   structure  - Current bin structure (from loadStructureFile)
+ * @returns {Promise<Object<string,string>>}
+ */
+async function buildDescriptorPrePass(extensionEntries, structure) {
+  const { mapping, warnings } = buildDescriptorMapping(extensionEntries);
+
+  for (const w of warnings) log.warn(`  descriptor_definition: ${w}`);
+
+  // Always create Unsupported/ — even if empty, users see at a glance what couldn't be mapped
+  await mkdir(EXTENSION_UNSUPPORTED_DIR, { recursive: true });
+  log.dim(`  ${EXTENSION_UNSUPPORTED_DIR}/`);
+
+  // Create one sub-directory per mapped descriptor name
+  for (const dirName of new Set(Object.values(mapping))) {
+    const fullDir = `${EXTENSION_DESCRIPTORS_DIR}/${dirName}`;
+    await mkdir(fullDir, { recursive: true });
+    log.dim(`  ${fullDir}/`);
+  }
+
+  await saveDescriptorMapping(structure, mapping);
+  log.dim(`  Saved descriptorMapping to .dbo/structure.json`);
+
+  return mapping;
+}
+
+/**
+ * Resolve filename column and content extraction preferences for one descriptor.
+ * Prompts the user on first use; saves to config.json; respects -y and --force.
+ *
+ * @param {string}   descriptor  - e.g. "documentation", "include", "control"
+ * @param {Object[]} records     - All extension records sharing this descriptor
+ * @param {Object}   options     - CLI options (options.yes, options.force)
+ * @returns {Promise<{ filenameCol: string, contentColsToExtract: Array<{col,ext}> }>}
+ */
+async function resolveDescriptorPreferences(descriptor, records, options) {
+  const sampleRecord = records[0];
+  const columns = Object.keys(sampleRecord)
+    .filter(k => k !== 'children' && !k.startsWith('_'));
+
+  // ── Filename column ──────────────────────────────────────────────────
+  let filenameCol;
+  const savedCol = await loadDescriptorFilenamePreference(descriptor);
+
+  if (options.yes) {
+    filenameCol = columns.includes('Name') ? 'Name'
+      : columns.includes('UID') ? 'UID' : columns[0];
+  } else if (savedCol && !options.force) {
+    filenameCol = savedCol;
+    log.dim(`  Filename column for "${descriptor}": "${filenameCol}" (saved)`);
+  } else {
+    const inquirer = (await import('inquirer')).default;
+    const defaultCol = columns.includes('Name') ? 'Name'
+      : columns.includes('UID') ? 'UID' : columns[0];
+    const { col } = await inquirer.prompt([{
+      type: 'list', name: 'col',
+      message: `Filename column for "${descriptor}" extensions:`,
+      choices: columns, default: defaultCol,
+    }]);
+    filenameCol = col;
+    await saveDescriptorFilenamePreference(descriptor, filenameCol);
+    log.dim(`  Saved filename column for "${descriptor}": "${filenameCol}"`);
+  }
+
+  // ── Content extraction ───────────────────────────────────────────────
+  const contentColsToExtract = [];
+  if (!options.yes) {
+    const base64Cols = [];
+    for (const record of records) {
+      for (const [key, value] of Object.entries(record)) {
+        if (key === 'children' || key.startsWith('_')) continue;
+        if (value && typeof value === 'object' && !Array.isArray(value)
+            && value.encoding === 'base64' && value.value !== null) {
+          if (!base64Cols.find(c => c.col === key)) {
+            let snippet = '';
+            try {
+              const decoded = Buffer.from(value.value, 'base64').toString('utf8');
+              snippet = decoded.substring(0, 80)
+                .replace(/[\x00-\x1f\x7f]/g, ' ')   // strip control chars (incl. \n, \r, \t, ESC)
+                .replace(/\s+/g, ' ')                  // collapse whitespace
+                .trim();
+              if (decoded.length > 80) snippet += '…';
+            } catch {}
+            base64Cols.push({ col: key, snippet });
+          }
+        }
+      }
+    }
+
+    if (base64Cols.length > 0) {
+      const savedExtractions = options.force
+        ? null
+        : await loadDescriptorContentExtractions(descriptor);
+      const newPreferences = savedExtractions ? { ...savedExtractions } : {};
+      let changed = false;
+      const inquirer = (await import('inquirer')).default;
+
+      for (const { col, snippet } of base64Cols) {
+        if (savedExtractions) {
+          const saved = savedExtractions[col];
+          if (saved === false) { log.dim(`  Skip "${col}" for "${descriptor}" (saved)`); continue; }
+          if (typeof saved === 'string') {
+            log.dim(`  Extracting "${col}" for "${descriptor}" as .${saved} (saved)`);
+            contentColsToExtract.push({ col, ext: saved });
+            continue;
+          }
+        }
+        const preview = snippet ? ` ("${snippet}")` : '';
+        const { extract } = await inquirer.prompt([{
+          type: 'confirm', name: 'extract',
+          message: `Extract column "${col}" (${descriptor}) as companion file?${preview}`,
+          default: true,
+        }]);
+        if (extract) {
+          const guessed = guessExtensionForDescriptor(descriptor, col);
+          const { ext } = await inquirer.prompt([{
+            type: 'input', name: 'ext',
+            message: `File extension for "${col}" (${descriptor}):`,
+            default: guessed,
+          }]);
+          const cleanExt = ext.replace(/^\./, '');
+          contentColsToExtract.push({ col, ext: cleanExt });
+          newPreferences[col] = cleanExt;
+        } else {
+          newPreferences[col] = false;
+        }
+        changed = true;
+      }
+      if (changed) await saveDescriptorContentExtractions(descriptor, newPreferences);
+    }
+  }
+
+  return { filenameCol, contentColsToExtract };
+}
+
+/**
+ * Guess a file extension based on descriptor name, with column-name fallback.
+ */
+function guessExtensionForDescriptor(descriptor, columnName) {
+  if (descriptor === 'documentation') return 'md';
+  if (descriptor === 'include') return 'html';
+  if (descriptor === 'control') return 'js';
+  return guessExtensionForColumn(columnName);
+}
+
+/**
+ * Resolve placement for documentation descriptor MD companion files.
+ * Prompts on first use; persists to config.json; respects -y and --force.
+ * @returns {Promise<'inline'|'root'>}
+ */
+async function resolveDocumentationPlacement(options) {
+  if (options.yes) return 'inline';
+
+  const saved = await loadExtensionDocumentationMDPlacement();
+  if (saved && !options.force) {
+    log.dim(`  Documentation MD placement: ${saved} (saved)`);
+    return saved;
+  }
+
+  const inquirer = (await import('inquirer')).default;
+  const { placement } = await inquirer.prompt([{
+    type: 'list', name: 'placement',
+    message: 'Where should extracted documentation MD files be placed?',
+    choices: [
+      { name: '/Documentation/<filename>.md  — project root (recommended)', value: 'root' },
+      { name: 'Extensions/Documentation/<filename>.md  — inline alongside metadata', value: 'inline' },
+    ],
+    default: 'root',
+  }]);
+
+  await saveExtensionDocumentationMDPlacement(placement);
+  log.dim(`  Saved documentation MD placement: "${placement}"`);
+  return placement;
+}
+
+/**
+ * Process extension entity records into descriptor-organized sub-directories.
+ *
+ * @param {Object[]} entries   - All extension records from appJson.children.extension
+ * @param {Object}   structure - Bin structure from loadStructureFile()
+ * @param {Object}   options   - CLI options (options.yes, options.force, options.entity)
+ * @param {string}   serverTz  - Server timezone for timestamp syncing
+ * @returns {Promise<Array<{uid, metaPath}>>}
+ */
+async function processExtensionEntries(entries, structure, options, serverTz) {
+  if (!entries || entries.length === 0) return [];
+
+  // --descriptor-types false → skip descriptor sorting, use flat Extensions/ via generic path
+  if (options.descriptorTypes === 'false') {
+    log.info(`Processing ${entries.length} extension record(s) (flat mode)...`);
+    return await processEntityDirEntries('extension', entries, options, serverTz);
+  }
+
+  log.info(`Processing ${entries.length} extension record(s)...`);
+
+  // Step A: Pre-pass — build mapping + create directories
+  const mapping = await buildDescriptorPrePass(entries, structure);
+
+  // Clear documentation preferences when --force is used with --documentation-only
+  if (options.documentationOnly && options.force) {
+    await saveDescriptorFilenamePreference('documentation', null);
+    await saveDescriptorContentExtractions('documentation', null);
+    await saveExtensionDocumentationMDPlacement(null);
+    log.info('  --force: cleared saved documentation preferences');
+  }
+
+  // Step B: Group records by descriptor
+  const groups = new Map(); // descriptor → { dir, records[] }
+  for (const record of entries) {
+    const descriptor = record.Descriptor || '__unsupported__';
+
+    // --documentation-only: skip non-documentation records
+    if (options.documentationOnly && descriptor !== 'documentation') continue;
+
+    if (!groups.has(descriptor)) {
+      groups.set(descriptor, { dir: resolveExtensionSubDir(record, mapping), records: [] });
+    }
+    groups.get(descriptor).records.push(record);
+  }
+
+  // Step C: Resolve preferences per descriptor (prompts fire here, before file writes)
+  const descriptorPrefs = new Map();
+  let docPlacement = 'inline';
+
+  for (const [descriptor, { records }] of groups.entries()) {
+    if (descriptor === '__unsupported__') {
+      descriptorPrefs.set(descriptor, { filenameCol: null, contentColsToExtract: [] });
+      continue;
+    }
+    const prefs = await resolveDescriptorPreferences(descriptor, records, options);
+    descriptorPrefs.set(descriptor, prefs);
+
+    if (descriptor === 'documentation') {
+      docPlacement = await resolveDocumentationPlacement(options);
+      if (docPlacement === 'root') {
+        await mkdir(DOCUMENTATION_DIR, { recursive: true });
+        log.dim(`  ${DOCUMENTATION_DIR}/`);
+      }
+    }
+  }
+
+  // Step D: Write files, one group at a time
+  const refs = [];
+  const bulkAction = { value: null };
+  const config = await loadConfig();
+
+  for (const [descriptor, { dir, records }] of groups.entries()) {
+    const { filenameCol, contentColsToExtract } = descriptorPrefs.get(descriptor);
+    const useRootDoc = (descriptor === 'documentation' && docPlacement === 'root');
+    const mdColInfo = useRootDoc ? contentColsToExtract.find(c => c.ext === 'md') : null;
+
+    log.info(`Processing ${records.length} "${descriptor}" extension(s) → ${dir}/`);
+
+    for (const record of records) {
+      // Resolve filename
+      let name;
+      if (filenameCol && record[filenameCol] != null) {
+        name = sanitizeFilename(String(record[filenameCol]));
+      } else if (record.Name) {
+        name = sanitizeFilename(String(record.Name));
+      } else {
+        name = sanitizeFilename(String(record.UID || 'untitled'));
+      }
+
+      const uid = record.UID || 'untitled';
+      const finalName = name === uid ? uid : `${name}.${uid}`;
+      const metaPath = join(dir, `${finalName}.metadata.json`);
+
+      // Change detection — same pattern as processEntityDirEntries()
+      const hasNewExtractions = contentColsToExtract.length > 0;
+      if (await fileExists(metaPath) && !options.yes && !hasNewExtractions) {
+        if (bulkAction.value === 'skip_all') {
+          log.dim(`  Skipped ${finalName}`);
+          refs.push({ uid: record.UID, metaPath });
+          continue;
+        }
+        if (bulkAction.value !== 'overwrite_all') {
+          const cfgWithTz = { ...config, ServerTimezone: serverTz };
+          const localSyncTime = await getLocalSyncTime(metaPath);
+          const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, cfgWithTz);
+          const serverDate = parseServerDate(record._LastUpdated, serverTz);
+
+          if (serverNewer) {
+            const action = await promptChangeDetection(finalName, record, cfgWithTz, { serverDate, localDate: localSyncTime });
+            if (action === 'skip') { refs.push({ uid: record.UID, metaPath }); continue; }
+            if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: record.UID, metaPath }); continue; }
+            if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+            if (action === 'compare') { await inlineDiffAndMerge(record, metaPath, cfgWithTz); refs.push({ uid: record.UID, metaPath }); continue; }
+          } else {
+            const localModified = await hasLocalModifications(metaPath, cfgWithTz);
+            if (localModified) {
+              const action = await promptChangeDetection(finalName, record, cfgWithTz, { localIsNewer: true, serverDate, localDate: localSyncTime });
+              if (action === 'skip') { refs.push({ uid: record.UID, metaPath }); continue; }
+              if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: record.UID, metaPath }); continue; }
+              if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+              if (action === 'compare') { await inlineDiffAndMerge(record, metaPath, cfgWithTz, { localIsNewer: true }); refs.push({ uid: record.UID, metaPath }); continue; }
+            } else {
+              log.dim(`  Up to date: ${finalName}`);
+              refs.push({ uid: record.UID, metaPath });
+              continue;
+            }
+          }
+        }
+      }
+
+      // Build metadata object
+      const meta = {};
+      const extractedCols = [];
+
+      for (const [key, value] of Object.entries(record)) {
+        if (key === 'children') continue;
+
+        const extractInfo = contentColsToExtract.find(c => c.col === key);
+        if (extractInfo && value && typeof value === 'object'
+            && value.encoding === 'base64' && value.value !== null) {
+          const decoded = resolveContentValue(value);
+          if (decoded) {
+            let colFilePath, refValue;
+
+            if (mdColInfo && extractInfo.col === mdColInfo.col) {
+              // Root placement: Documentation/<name>.md
+              const docFileName = `${name}.md`;
+              colFilePath = join(DOCUMENTATION_DIR, docFileName);
+              refValue = `@/${DOCUMENTATION_DIR}/${docFileName}`;
+            } else {
+              const colFileName = `${finalName}.${key}.${extractInfo.ext}`;
+              colFilePath = join(dir, colFileName);
+              refValue = `@${colFileName}`;
+            }
+
+            meta[key] = refValue;
+            await writeFile(colFilePath, decoded);
+            extractedCols.push(key);
+            if (serverTz) {
+              try { await setFileTimestamps(colFilePath, record._CreatedOn, record._LastUpdated, serverTz); } catch {}
+            }
+            log.dim(`  → ${colFilePath}`);
+            continue;
+          }
+        }
+
+        // Inline or non-extraction columns
+        if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
+          meta[key] = resolveContentValue(value);
+        } else {
+          meta[key] = value;
+        }
+      }
+
+      meta._entity = 'extension';
+      if (extractedCols.length > 0) meta._contentColumns = extractedCols;
+
+      await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+      if (serverTz) {
+        try { await setFileTimestamps(metaPath, record._CreatedOn, record._LastUpdated, serverTz); } catch {}
+      }
+      log.success(`Saved ${metaPath}`);
+      refs.push({ uid: record.UID, metaPath });
+    }
+  }
+
+  return refs;
+}
+
 /**
  * Process media entries: download binary files from server + create metadata.
  * Media uses Filename (not Name) and files are fetched via /api/media/{uid}.
@@ -1292,11 +1914,20 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       }
 
       if (mediaBulkAction.value !== 'overwrite_all') {
+        // Use explicit serverTz (not config.ServerTimezone) to ensure consistency
+        // with how setFileTimestamps set the mtime — the two must use the same timezone.
+        const configWithTz = { ...config, ServerTimezone: serverTz };
         const localSyncTime = await getLocalSyncTime(metaPath);
-        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, config);
+        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+        const serverDate = parseServerDate(record._LastUpdated, serverTz);
+        const diffable = isDiffable(ext);
 
         if (serverNewer) {
-          const action = await promptChangeDetection(dedupName, record, config);
+          const action = await promptChangeDetection(dedupName, record, configWithTz, {
+            diffable,
+            serverDate,
+            localDate: localSyncTime,
+          });
 
           if (action === 'skip') {
             log.dim(`  Skipped ${finalFilename}`);
@@ -1314,15 +1945,21 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
           }
           if (action === 'compare') {
             // For binary media, show metadata diffs only
-            await inlineDiffAndMerge(record, metaPath, config);
+            await inlineDiffAndMerge(record, metaPath, configWithTz);
             refs.push({ uid: record.UID, metaPath });
             continue;
           }
         } else {
           // Server _LastUpdated hasn't changed — check for local modifications
-          const locallyModified = await hasLocalModifications(metaPath, config);
+          const locallyModified = await hasLocalModifications(metaPath, configWithTz);
           if (locallyModified) {
-            const action = await promptChangeDetection(dedupName, record, config, { localIsNewer: true });
+            const localDate = localSyncTime; // mtime already fetched above
+            const action = await promptChangeDetection(dedupName, record, configWithTz, {
+              localIsNewer: true,
+              diffable,
+              serverDate,
+              localDate,
+            });
 
             if (action === 'skip') {
               log.dim(`  Kept local: ${finalFilename}`);
@@ -1339,7 +1976,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
               mediaBulkAction.value = 'overwrite_all';
             }
             if (action === 'compare') {
-              await inlineDiffAndMerge(record, metaPath, config, { localIsNewer: true });
+              await inlineDiffAndMerge(record, metaPath, configWithTz, { localIsNewer: true });
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
@@ -1397,10 +2034,13 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
     log.dim(`  → ${metaPath}`);
 
-    // Set file timestamps from server dates
+    // Set file timestamps from server dates (independent try-catch so one failure
+    // doesn't prevent the other — metaPath mtime is the sync baseline for comparisons)
     if (serverTz && (record._CreatedOn || record._LastUpdated)) {
       try {
         await setFileTimestamps(filePath, record._CreatedOn, record._LastUpdated, serverTz);
+      } catch { /* non-critical */ }
+      try {
         await setFileTimestamps(metaPath, record._CreatedOn, record._LastUpdated, serverTz);
       } catch { /* non-critical */ }
     }
@@ -1573,12 +2213,17 @@ async function processRecord(entityName, record, structure, options, usedNames,
     }
 
     if (bulkAction.value !== 'overwrite_all') {
-      const localSyncTime = await getLocalSyncTime(metaPath);
       const config = await loadConfig();
-      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, config);
+      const configWithTz = { ...config, ServerTimezone: serverTz };
+      const localSyncTime = await getLocalSyncTime(metaPath);
+      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+      const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
       if (serverNewer) {
-        const action = await promptChangeDetection(finalName, record, config);
+        const action = await promptChangeDetection(finalName, record, configWithTz, {
+          serverDate,
+          localDate: localSyncTime,
+        });
 
         if (action === 'skip') {
           log.dim(`  Skipped ${finalName}.${ext}`);
@@ -1594,16 +2239,20 @@ async function processRecord(entityName, record, structure, options, usedNames,
           // Fall through to write
         }
         if (action === 'compare') {
-          await inlineDiffAndMerge(record, metaPath, config);
+          await inlineDiffAndMerge(record, metaPath, configWithTz);
           return { uid: record.UID, metaPath };
         }
         // 'overwrite' falls through to normal write
       } else {
         // Server _LastUpdated hasn't changed since last sync.
         // Check if local content files were modified (user edits).
-        const locallyModified = await hasLocalModifications(metaPath, config);
+        const locallyModified = await hasLocalModifications(metaPath, configWithTz);
         if (locallyModified) {
-          const action = await promptChangeDetection(finalName, record, config, { localIsNewer: true });
+          const action = await promptChangeDetection(finalName, record, configWithTz, {
+            localIsNewer: true,
+            serverDate,
+            localDate: localSyncTime,
+          });
 
           if (action === 'skip') {
             log.dim(`  Kept local: ${finalName}.${ext}`);
@@ -1618,7 +2267,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
             bulkAction.value = 'overwrite_all';
           }
           if (action === 'compare') {
-            await inlineDiffAndMerge(record, metaPath, config, { localIsNewer: true });
+            await inlineDiffAndMerge(record, metaPath, configWithTz, { localIsNewer: true });
             return { uid: record.UID, metaPath };
           }
           // 'overwrite' falls through to normal write
@@ -1700,6 +2349,570 @@ export function guessExtensionForColumn(columnName) {
   return 'txt';
 }
 
+// ─── Output Hierarchy Processing ──────────────────────────────────────────
+
+/**
+ * Build a tree structure from flat output entity arrays.
+ * Groups columns, joins, and filters under their parent output records.
+ *
+ * @param {Object} appJson - The full app JSON with children arrays
+ * @returns {Array} - Array of output root nodes with nested _children
+ */
+export function buildOutputHierarchyTree(appJson) {
+  const outputs = appJson.children.output || [];
+  const columns = appJson.children.output_value || [];
+  const filters = appJson.children.output_value_filter || [];
+  const joins = appJson.children.output_value_entity_column_rel || [];
+
+  if (outputs.length === 0) return [];
+
+  // Index all entities by their numeric ID for O(1) lookups
+  const outputById = new Map();
+  const columnById = new Map();
+  const joinById = new Map();
+
+  for (const o of outputs) {
+    outputById.set(o.OutputID || o._id, { ...o, _children: { column: [], join: [], filter: [] } });
+  }
+  for (const c of columns) {
+    columnById.set(c.OutputValueID || c._id, { ...c, _children: { filter: [] } });
+  }
+  for (const j of joins) {
+    joinById.set(j.OutputValueEntityColumnRelID || j._id, { ...j, _children: { column: [] } });
+  }
+
+  // Attach filters: to column (via OutputValueID) or directly to output (via OutputID)
+  for (const f of filters) {
+    if (f.OutputValueID) {
+      const parent = columnById.get(f.OutputValueID);
+      if (parent) {
+        parent._children.filter.push({ ...f });
+        continue;
+      }
+    }
+    if (f.OutputID) {
+      const parent = outputById.get(f.OutputID);
+      if (parent) {
+        parent._children.filter.push({ ...f });
+      }
+    }
+  }
+
+  // Attach columns: to join (via OutputValueEntityColumnRelID) or directly to output (via OutputID)
+  for (const [, col] of columnById) {
+    if (col.OutputValueEntityColumnRelID) {
+      const parent = joinById.get(col.OutputValueEntityColumnRelID);
+      if (parent) {
+        parent._children.column.push(col);
+        continue;
+      }
+    }
+    if (col.OutputID) {
+      const parent = outputById.get(col.OutputID);
+      if (parent) {
+        parent._children.column.push(col);
+      }
+    }
+  }
+
+  // Attach joins to outputs (via OutputID)
+  for (const [, j] of joinById) {
+    if (j.OutputID) {
+      const parent = outputById.get(j.OutputID);
+      if (parent) {
+        parent._children.join.push(j);
+      }
+    }
+  }
+
+  // Sort children by OrderNumber (ties broken by array index stability)
+  const sortByOrder = (a, b) => (a.OrderNumber || 0) - (b.OrderNumber || 0);
+
+  for (const [, output] of outputById) {
+    output._children.column.sort(sortByOrder);
+    output._children.join.sort(sortByOrder);
+    output._children.filter.sort(sortByOrder);
+
+    for (const col of output._children.column) {
+      col._children.filter.sort(sortByOrder);
+    }
+    for (const j of output._children.join) {
+      j._children.column.sort(sortByOrder);
+      for (const col of j._children.column) {
+        col._children.filter.sort(sortByOrder);
+      }
+    }
+  }
+
+  return Array.from(outputById.values());
+}
+
+/**
+ * Resolve filename column preferences for each output entity type.
+ * Loads from config, prompts if needed, saves choices.
+ *
+ * @param {Object} appJson - The full app JSON
+ * @param {Object} options - CLI options
+ * @returns {Object} - { output: 'Name', output_value: 'Title', ... }
+ */
+async function resolveOutputFilenameColumns(appJson, options) {
+  const defaults = {
+    output: 'Name',
+    output_value: 'Title',
+    output_value_filter: 'ShortName',
+    output_value_entity_column_rel: 'UID',
+  };
+  const fallbacks = {
+    output: ['Name', 'Title', 'OrderNumber', 'UID'],
+    output_value: ['Title', 'Name', 'OrderNumber', 'UID'],
+    output_value_filter: ['ShortName', 'Name', 'UID'],
+    output_value_entity_column_rel: ['UID'],
+  };
+  const docNames = OUTPUT_ENTITY_MAP;
+  const result = {};
+
+  for (const entityKey of OUTPUT_HIERARCHY_ENTITIES) {
+    // Check saved preference
+    const saved = await loadOutputFilenamePreference(entityKey);
+    if (saved) {
+      result[entityKey] = saved;
+      continue;
+    }
+
+    // In -y mode use defaults
+    if (options.yes) {
+      result[entityKey] = defaults[entityKey];
+      await saveOutputFilenamePreference(entityKey, defaults[entityKey]);
+      continue;
+    }
+
+    // Find a sample record to get available columns
+    const records = appJson.children[entityKey] || [];
+    if (records.length === 0) {
+      result[entityKey] = defaults[entityKey];
+      continue;
+    }
+
+    const sampleRecord = records[0];
+    const columns = Object.keys(sampleRecord).filter(k => k !== 'children' && !k.startsWith('_'));
+
+    // Find best default from fallback chain
+    let defaultCol = defaults[entityKey];
+    for (const fb of fallbacks[entityKey]) {
+      if (columns.includes(fb)) { defaultCol = fb; break; }
+    }
+
+    const inquirer = (await import('inquirer')).default;
+    const { col } = await inquirer.prompt([{
+      type: 'list',
+      name: 'col',
+      message: `Which column should be used as the filename for ${docNames[entityKey]} (${entityKey}) records?`,
+      choices: columns,
+      default: defaultCol,
+    }]);
+
+    result[entityKey] = col;
+    await saveOutputFilenamePreference(entityKey, col);
+    log.dim(`  Saved filename column preference for ${entityKey}`);
+  }
+
+  return result;
+}
+
+/**
+ * Build a filename for an output hierarchy entity.
+ * Uses dot-separated hierarchical naming: _output~<name>~<uid>.column~<name>~<uid>.json
+ *
+ * @param {string} entityType - Documentation name: 'output', 'column', 'join', 'filter'
+ * @param {Object} node - The entity record
+ * @param {string} filenameCol - Column to use for the name portion
+ * @param {string[]} parentChain - Array of parent segments: ['_output~name~uid', 'join~name~uid', ...]
+ * @returns {string} - Base filename without extension
+ */
+export function buildOutputFilename(entityType, node, filenameCol, parentChain = []) {
+  const uid = node.UID || '';
+  const rawName = node[filenameCol];
+  const name = rawName ? sanitizeFilename(String(rawName)) : '';
+
+  // Build this entity's segment: <type>~<name>~<uid>
+  // If filenameCol IS the UID, don't double-append it
+  let segment;
+  if (!name || name === uid) {
+    segment = `${entityType}~${uid}`;
+  } else {
+    segment = `${entityType}~${name}~${uid}`;
+  }
+
+  // Root output gets _ prefix
+  if (entityType === 'output') {
+    segment = `_${segment}`;
+  }
+
+  const allSegments = [...parentChain, segment];
+  return allSegments.join('.');
+}
+
+/**
+ * Parse an output hierarchy filename back into entity relationships.
+ *
+ * @param {string} filename - e.g. "_output~name~uid.column~name~uid.filter~name~uid.json"
+ * @returns {Object} - { segments: [{entity, name, uid}], rootOutputUid, entityType, uid }
+ */
+export function parseOutputHierarchyFile(filename) {
+  // Strip .json extension
+  let base = filename;
+  if (base.endsWith('.json')) base = base.substring(0, base.length - 5);
+
+  // Split into segments by finding entity type boundaries
+  // Entity types are: _output~, output~, column~, join~, filter~
+  const parts = [];
+
+  // First, split by '.' but we need to be careful since names can contain '.'
+  // Strategy: find entity-type prefixed segments
+  // Split on '.' then re-join segments that don't start with an entity type
+  const dotParts = base.split('.');
+  let currentSegment = null;
+
+  for (const part of dotParts) {
+    // Check if this part starts with an entity type prefix
+    const stripped = part.replace(/^_/, '');
+    const match = stripped.match(/^(output|column|join|filter)~/);
+
+    if (match) {
+      if (currentSegment !== null) {
+        parts.push(currentSegment);
+      }
+      currentSegment = part;
+    } else if (currentSegment !== null) {
+      // This part belongs to the previous segment (name contained '.')
+      currentSegment += '.' + part;
+    } else {
+      currentSegment = part;
+    }
+  }
+  if (currentSegment !== null) {
+    parts.push(currentSegment);
+  }
+
+  // Parse each segment: <type>~<name>~<uid> or <type>~<uid>
+  const segments = [];
+  for (const part of parts) {
+    const stripped = part.replace(/^_/, '');
+    const firstTilde = stripped.indexOf('~');
+    if (firstTilde < 0) continue;
+
+    const entityType = stripped.substring(0, firstTilde);
+    const rest = stripped.substring(firstTilde + 1);
+
+    // The UID is the last ~-separated value (UIDs are alphanumeric, typically 8+ chars)
+    const lastTilde = rest.lastIndexOf('~');
+    let name, uid;
+    if (lastTilde >= 0) {
+      name = rest.substring(0, lastTilde);
+      uid = rest.substring(lastTilde + 1);
+    } else {
+      // No second tilde — the entire rest is the UID
+      name = null;
+      uid = rest;
+    }
+
+    segments.push({ entity: entityType, name, uid });
+  }
+
+  if (segments.length === 0) return null;
+
+  const last = segments[segments.length - 1];
+  const root = segments[0];
+
+  // Map documentation name back to physical table name
+  const docToPhysical = {
+    output: 'output',
+    column: 'output_value',
+    filter: 'output_value_filter',
+    join: 'output_value_entity_column_rel',
+  };
+
+  return {
+    segments,
+    rootOutputUid: root.uid,
+    entityType: last.entity,
+    physicalEntity: docToPhysical[last.entity] || last.entity,
+    uid: last.uid,
+    parentEntity: segments.length > 1 ? segments[segments.length - 2].entity : null,
+    parentUid: segments.length > 1 ? segments[segments.length - 2].uid : null,
+  };
+}
+
+/**
+ * Main orchestrator: process output hierarchy entities during clone.
+ * Builds tree, resolves filenames, writes hierarchy files.
+ *
+ * @param {Object} appJson - The full app JSON
+ * @param {Object} structure - Bin hierarchy structure
+ * @param {Object} options - CLI options
+ * @param {string} serverTz - Server timezone
+ * @returns {Array} - Array of { uid, metaPath } for app.json reference replacement
+ */
+async function processOutputHierarchy(appJson, structure, options, serverTz) {
+  const tree = buildOutputHierarchyTree(appJson);
+  if (tree.length === 0) return [];
+
+  log.info(`Processing ${tree.length} output record(s) with hierarchy...`);
+
+  // Resolve filename columns for each entity type
+  const filenameCols = await resolveOutputFilenameColumns(appJson, options);
+
+  const refs = [];
+  const bulkAction = { value: null };
+  const config = await loadConfig();
+  const configWithTz = { ...config, ServerTimezone: serverTz };
+  // When --force flag is set, skip change detection and re-process all files
+  const forceReprocess = !!options.force;
+
+  for (const output of tree) {
+    // Resolve bin directory for this output
+    let binDir = null;
+    let chosenBinId = null;
+    if (output.BinID && structure[output.BinID]) {
+      binDir = resolveBinPath(output.BinID, structure);
+    }
+
+    if (!binDir) {
+      // No BinID — prompt or default
+      if (!options.yes) {
+        const inquirer = (await import('inquirer')).default;
+        const binChoices = Object.entries(structure).map(([id, entry]) => ({
+          name: `${entry.name} (${entry.fullPath})`,
+          value: id,
+        }));
+
+        if (binChoices.length > 0) {
+          const { binId } = await inquirer.prompt([{
+            type: 'list',
+            name: 'binId',
+            message: `Output "${output.Name || output.UID}" has no BinID. Which bin should it go in?`,
+            choices: binChoices,
+          }]);
+          chosenBinId = Number(binId);
+          binDir = resolveBinPath(chosenBinId, structure);
+        } else {
+          binDir = BINS_DIR;
+        }
+      } else {
+        binDir = BINS_DIR;
+      }
+    }
+
+    await mkdir(binDir, { recursive: true });
+
+    // Build root output filename
+    const rootBasename = buildOutputFilename('output', output, filenameCols.output);
+    const rootMetaPath = join(binDir, `${rootBasename}.json`);
+
+    // Change detection for existing files (skip when --entity forces re-processing)
+    if (await fileExists(rootMetaPath) && !options.yes && !forceReprocess) {
+      if (bulkAction.value === 'skip_all') {
+        log.dim(`  Skipped ${rootBasename}`);
+        refs.push({ uid: output.UID, metaPath: rootMetaPath });
+        continue;
+      }
+      if (bulkAction.value !== 'overwrite_all') {
+        const localSyncTime = await getLocalSyncTime(rootMetaPath);
+        const serverNewer = isServerNewer(localSyncTime, output._LastUpdated, configWithTz);
+        const serverDate = parseServerDate(output._LastUpdated, serverTz);
+        if (serverNewer) {
+          const action = await promptChangeDetection(rootBasename, output, configWithTz, { serverDate, localDate: localSyncTime });
+          if (action === 'skip') { refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+          if (action === 'compare') { await inlineDiffAndMerge(output, rootMetaPath, configWithTz); refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+        } else {
+          const locallyModified = await hasLocalModifications(rootMetaPath, configWithTz);
+          if (locallyModified) {
+            const action = await promptChangeDetection(rootBasename, output, configWithTz, { localIsNewer: true, serverDate, localDate: localSyncTime });
+            if (action === 'skip') { refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+            if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+            if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+            if (action === 'compare') { await inlineDiffAndMerge(output, rootMetaPath, configWithTz, { localIsNewer: true }); refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          } else {
+            log.dim(`  Up to date: ${rootBasename}`);
+            refs.push({ uid: output.UID, metaPath: rootMetaPath });
+            continue;
+          }
+        }
+      }
+    }
+
+    // Collect child file references for root JSON
+    const childRefs = { column: [], join: [], filter: [] };
+
+    // Helper to build a child filename segment
+    const childSegment = (type, node, col) => {
+      const uid = node.UID || '';
+      const rawName = node[col];
+      const name = rawName ? sanitizeFilename(String(rawName)) : '';
+      return (!name || name === uid) ? `${type}~${uid}` : `${type}~${name}~${uid}`;
+    };
+
+    // Process all children depth-first
+    // Direct filters on output
+    for (const filter of output._children.filter) {
+      const filterName = `${rootBasename}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+      const filterPath = join(binDir, `${filterName}.json`);
+      await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+      childRefs.filter.push(`@${filterPath}`);
+    }
+
+    // Direct columns on output
+    for (const col of output._children.column) {
+      const colSeg = childSegment('column', col, filenameCols.output_value);
+      const colName = `${rootBasename}.${colSeg}`;
+      const colPath = join(binDir, `${colName}.json`);
+      await writeOutputEntityFile(col, 'output_value', colPath, serverTz);
+      childRefs.column.push(`@${colPath}`);
+
+      // Filters under this column
+      for (const filter of col._children.filter) {
+        const filterName = `${colName}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+        const filterPath = join(binDir, `${filterName}.json`);
+        await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+        childRefs.filter.push(`@${filterPath}`);
+      }
+    }
+
+    // Joins on output
+    for (const j of output._children.join) {
+      const joinSeg = childSegment('join', j, filenameCols.output_value_entity_column_rel);
+      const joinName = `${rootBasename}.${joinSeg}`;
+      const joinPath = join(binDir, `${joinName}.json`);
+      await writeOutputEntityFile(j, 'output_value_entity_column_rel', joinPath, serverTz);
+      childRefs.join.push(`@${joinPath}`);
+
+      // Columns under this join
+      for (const col of j._children.column) {
+        const joinColName = `${joinName}.${childSegment('column', col, filenameCols.output_value)}`;
+        const joinColPath = join(binDir, `${joinColName}.json`);
+        await writeOutputEntityFile(col, 'output_value', joinColPath, serverTz);
+        childRefs.column.push(`@${joinColPath}`);
+
+        // Filters under this join→column
+        for (const filter of col._children.filter) {
+          const filterName = `${joinColName}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+          const filterPath = join(binDir, `${filterName}.json`);
+          await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+          childRefs.filter.push(`@${filterPath}`);
+        }
+      }
+    }
+
+    // Write root output JSON with child references
+    const rootMeta = {};
+    const rootContentColumns = [];
+    for (const [key, value] of Object.entries(output)) {
+      if (key === '_children') continue;
+
+      // Always extract CustomSQL to companion .sql file
+      if (key === 'CustomSQL') {
+        const decoded = resolveContentValue(value);
+        const sqlContent = (decoded && decoded.trim()) ? decoded : '';
+        const sqlFilePath = rootMetaPath.replace(/\.json$/, '.CustomSQL.sql');
+        await writeFile(sqlFilePath, sqlContent);
+        rootMeta[key] = `@${basename(sqlFilePath)}`;
+        rootContentColumns.push('CustomSQL');
+        if (serverTz && (output._CreatedOn || output._LastUpdated)) {
+          try { await setFileTimestamps(sqlFilePath, output._CreatedOn, output._LastUpdated, serverTz); } catch { /* non-critical */ }
+        }
+        log.dim(`  → ${sqlFilePath}`);
+        continue;
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
+        rootMeta[key] = resolveContentValue(value);
+      } else {
+        rootMeta[key] = value;
+      }
+    }
+    rootMeta._entity = 'output';
+    if (rootContentColumns.length > 0) {
+      rootMeta._contentColumns = rootContentColumns;
+    }
+    rootMeta.children = childRefs;
+
+    // If user chose a bin for a BinID-less output, store it and mark as modified
+    if (chosenBinId) {
+      rootMeta.BinID = chosenBinId;
+      log.dim(`  Set BinID=${chosenBinId} on "${output.Name || output.UID}" (staged for next push)`);
+    }
+
+    await writeFile(rootMetaPath, JSON.stringify(rootMeta, null, 2) + '\n');
+    log.success(`Saved ${rootMetaPath}`);
+
+    // Set file timestamps to server's _LastUpdated so diff detection works.
+    // Skip when chosenBinId is set — keep mtime at "now" so push detects the local edit.
+    if (!chosenBinId && serverTz && (output._CreatedOn || output._LastUpdated)) {
+      try {
+        await setFileTimestamps(rootMetaPath, output._CreatedOn, output._LastUpdated, serverTz);
+      } catch { /* non-critical */ }
+    }
+
+    refs.push({ uid: output.UID, metaPath: rootMetaPath });
+  }
+
+  return refs;
+}
+
+/**
+ * Write a single output hierarchy entity file (column, join, or filter).
+ * Handles CustomSQL extraction to companion .sql files.
+ */
+async function writeOutputEntityFile(node, physicalEntity, filePath, serverTz) {
+  const meta = {};
+  const contentColumns = [];
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === '_children') continue;
+
+    // Always extract CustomSQL to companion .sql file
+    if (key === 'CustomSQL') {
+      const decoded = resolveContentValue(value);
+      const sqlContent = (decoded && decoded.trim()) ? decoded : '';
+      const sqlFilePath = filePath.replace(/\.json$/, '.CustomSQL.sql');
+      await writeFile(sqlFilePath, sqlContent);
+      meta[key] = `@${basename(sqlFilePath)}`;
+      contentColumns.push('CustomSQL');
+
+      if (serverTz && (node._CreatedOn || node._LastUpdated)) {
+        try {
+          await setFileTimestamps(sqlFilePath, node._CreatedOn, node._LastUpdated, serverTz);
+        } catch { /* non-critical */ }
+      }
+      log.dim(`  → ${sqlFilePath}`);
+      continue;
+    }
+
+    // Decode other base64 columns inline
+    if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
+      meta[key] = resolveContentValue(value);
+    } else {
+      meta[key] = value;
+    }
+  }
+
+  meta._entity = physicalEntity;
+  if (contentColumns.length > 0) {
+    meta._contentColumns = contentColumns;
+  }
+
+  await writeFile(filePath, JSON.stringify(meta, null, 2) + '\n');
+  log.dim(`  → ${filePath}`);
+
+  if (serverTz && (node._CreatedOn || node._LastUpdated)) {
+    try {
+      await setFileTimestamps(filePath, node._CreatedOn, node._LastUpdated, serverTz);
+    } catch { /* non-critical */ }
+  }
+}
+
 /**
  * Save app.json to project root with @ references replacing processed entries.
  */
@@ -1731,7 +2944,13 @@ async function saveAppJson(appJson, contentRefs, otherRefs, domain) {
   }
 
   // Bins stay as-is (directory structure, no metadata files)
-  // Output stays as-is (ignored for now)
+
+  // Remove sub-entity arrays that are now embedded in output hierarchy files
+  if (otherRefs.output) {
+    delete output.children.output_value;
+    delete output.children.output_value_filter;
+    delete output.children.output_value_entity_column_rel;
+  }
 
   await writeFile('app.json', JSON.stringify(output, null, 2) + '\n');
 }