@dboio/cli 0.6.7 → 0.6.9

package/README.md

@@ -253,6 +253,34 @@ dbo init --domain my-domain.com --app myapp --clone
 
 When cloning an app that was already cloned locally, the CLI detects existing files and compares modification times against the server's `_LastUpdated`. You'll be prompted to overwrite, compare differences, or skip — same as `dbo pull`. Use `-y` to auto-accept all changes.
 
+#### Collision detection
+
+When multiple records would create files at the same path (e.g., a `content` record and a `media` record both named `colors.css`), the CLI detects the collision before writing any files and prompts you to choose which record to keep:
+
+```
+⚠ Collision: 2 records want to create "Bins/app/colors.css"
+? Which record should create this file?
+❯ [content] colors (UID: abc123)
+  [media] colors.css (UID: def456)
+```
+
+The rejected record is automatically staged for deletion in `.dbo/synchronize.json`. Run `dbo push` to delete it from the server.
+
+In non-interactive mode (`-y`), the first record is kept and others are auto-staged for deletion.
+
+#### Stale media cleanup
+
+During media downloads, files returning 404 (no longer exist on the server) are collected as "stale records". After all downloads complete, you'll be prompted to stage them for deletion:
+
+```
+Found 3 stale media record(s) (404 - files no longer exist on server)
+? Stage these 3 stale media records for deletion? (y/N)
+```
+
+This helps keep your app clean by removing database records for media files that have been deleted from the server.
+
+In non-interactive mode (`-y`), stale cleanup is skipped (conservative default).
+
 #### Path resolution
 
 When a content record has both `Path` and `BinID`, the CLI prompts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/plugins/claude/dbo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbo",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"

package/src/commands/add.js

@@ -8,6 +8,7 @@ import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
 import { loadAppConfig } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 
 // Directories and patterns to skip when scanning with `dbo add .`
 const IGNORE_DIRS = new Set(['.dbo', '.git', 'node_modules', '.svn', '.hg']);
@@ -17,6 +18,7 @@ export const addCommand = new Command('add')
   .argument('<path>', 'File or "." to scan current directory')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')
@@ -26,6 +28,14 @@ export const addCommand = new Command('add')
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      if (modifyKeyResult.modifyKey) options._resolvedModifyKey = modifyKeyResult.modifyKey;
+
       if (targetPath === '.') {
         await addDirectory(process.cwd(), client, options);
       } else {
@@ -242,10 +252,21 @@ async function submitAdd(meta, metaPath, filePath, client, options) {
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (options._resolvedModifyKey) extraParams['_modify_key'] = options._resolvedModifyKey;
 
   let body = await buildInputBody(dataExprs, extraParams);
   let result = await client.postUrlEncoded('/api/input/submit', body);
 
+  // Reactive ModifyKey retry
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return null; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    options._resolvedModifyKey = retryMK.modifyKey;
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
   // Retry with prompted params if needed (ticket, user, repo mismatch)
   const retryResult = await checkSubmitErrors(result);
   if (retryResult) {

package/src/commands/clone.js

@@ -2,7 +2,7 @@ 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 } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
@@ -80,6 +80,342 @@ function resolvePathToBinsDir(pathValue, structure) {
   return `${BINS_DIR}/${dirPart}`;
 }
 
+/**
+ * Extract path components for content/generic records (read-only, no file writes).
+ * Replicates logic from processRecord() for collision detection.
+ */
+function resolveRecordPaths(entityName, record, structure, placementPref) {
+  let name = sanitizeFilename(String(record.Name || record.UID || 'untitled'));
+
+  // Determine extension (priority: Extension field > Name > Path)
+  let ext = '';
+  if (record.Extension) {
+    ext = String(record.Extension).toLowerCase();
+  } else {
+    if (record.Name) {
+      const extractedExt = extname(String(record.Name));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+    if (!ext && record.Path) {
+      const extractedExt = extname(String(record.Path));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+  }
+
+  // Strip double extension
+  if (ext) {
+    const extWithDot = `.${ext}`;
+    if (name.toLowerCase().endsWith(extWithDot)) {
+      name = name.substring(0, name.length - extWithDot.length);
+    }
+  }
+
+  // Resolve directory (BinID vs Path)
+  let dir = BINS_DIR;
+  const hasBinID = record.BinID && structure[record.BinID];
+  const hasPath = record.Path && typeof record.Path === 'string' && record.Path.trim();
+
+  if (hasBinID && hasPath) {
+    dir = placementPref === 'path' ? record.Path : resolveBinPath(record.BinID, structure);
+  } else if (hasBinID) {
+    dir = resolveBinPath(record.BinID, structure);
+  } else if (hasPath) {
+    dir = resolvePathToBinsDir(record.Path, structure);
+  }
+
+  // Clean directory path
+  dir = dir.replace(/^\/+|\/+$/g, '');
+  if (!dir) dir = BINS_DIR;
+  const pathExt = extname(dir);
+  if (pathExt) {
+    dir = dir.substring(0, dir.lastIndexOf('/')) || BINS_DIR;
+  }
+
+  const filename = ext ? `${name}.${ext}` : name;
+  const metaPath = join(dir, `${name}.metadata.json`);
+
+  return { dir, filename, metaPath };
+}
+
+/**
+ * Extract path components for media records.
+ * Replicates logic from processMediaEntries() for collision detection.
+ */
+function resolveMediaPaths(record, structure, placementPref) {
+  const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
+  const name = sanitizeFilename(filename.replace(/\.[^.]+$/, ''));
+  const ext = (record.Extension || 'bin').toLowerCase();
+
+  let dir = BINS_DIR;
+  const hasBinID = record.BinID && structure[record.BinID];
+  const hasFullPath = record.FullPath && typeof record.FullPath === 'string';
+
+  let fullPathDir = null;
+  if (hasFullPath) {
+    const stripped = record.FullPath.replace(/^\/+/, '');
+    const lastSlash = stripped.lastIndexOf('/');
+    fullPathDir = lastSlash >= 0 ? stripped.substring(0, lastSlash) : BINS_DIR;
+  }
+
+  if (hasBinID && fullPathDir && fullPathDir !== '.') {
+    dir = placementPref === 'path' ? fullPathDir : resolveBinPath(record.BinID, structure);
+  } else if (hasBinID) {
+    dir = resolveBinPath(record.BinID, structure);
+  } else if (fullPathDir && fullPathDir !== BINS_DIR) {
+    dir = fullPathDir;
+  }
+
+  dir = dir.replace(/^\/+|\/+$/g, '');
+  if (!dir) dir = BINS_DIR;
+
+  const finalFilename = `${name}.${ext}`;
+  const metaPath = join(dir, `${finalFilename}.metadata.json`);
+
+  return { dir, filename: finalFilename, metaPath };
+}
+
+/**
+ * Extract path components for entity-dir records.
+ * Simplified from processEntityDirEntries() for collision detection.
+ */
+function resolveEntityDirPaths(entityName, record, dirName) {
+  let name;
+  if (entityName === 'app_version' && record.Number) {
+    name = sanitizeFilename(String(record.Number));
+  } 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(dirName, `${finalName}.metadata.json`);
+  return { dir: dirName, filename: finalName, metaPath };
+}
+
+/**
+ * Build global registry of all files that will be created during clone.
+ * Returns Map<filePath, Array<{entity, record, dir, filename, metaPath}>>
+ */
+async function buildFileRegistry(appJson, structure, placementPrefs) {
+  const registry = new Map();
+
+  function addToRegistry(filePath, entity, record, dir, filename, metaPath) {
+    if (!registry.has(filePath)) {
+      registry.set(filePath, []);
+    }
+    registry.get(filePath).push({ entity, record, dir, filename, metaPath });
+  }
+
+  // Process content records
+  for (const record of (appJson.children.content || [])) {
+    const { dir, filename, metaPath } = resolveRecordPaths(
+      'content', record, structure, placementPrefs.contentPlacement
+    );
+    addToRegistry(join(dir, filename), 'content', record, dir, filename, metaPath);
+  }
+
+  // Process media records
+  for (const record of (appJson.children.media || [])) {
+    const { dir, filename, metaPath } = resolveMediaPaths(
+      record, structure, placementPrefs.mediaPlacement
+    );
+    addToRegistry(join(dir, filename), 'media', record, dir, filename, metaPath);
+  }
+
+  // Note: entity-dir records (Extensions/, Data Sources/, etc.) and generic entities
+  // are excluded from collision detection — they use UID-based naming to handle duplicates.
+  // Only content and media records in Bins/ are checked for cross-entity collisions.
+
+  return registry;
+}
+
+/**
+ * Detect collisions and prompt user to choose which record to keep.
+ * Uses stored resolutions from config and pending deletes from synchronize.json
+ * to avoid re-prompting on subsequent clones.
+ * Returns Set of UIDs to skip during processing.
+ */
+async function resolveCollisions(registry, options) {
+  const toDelete = new Set();
+  const savedResolutions = await loadCollisionResolutions();
+  const sync = await loadSynchronize();
+  const pendingDeleteUIDs = new Set((sync.delete || []).map(e => e.UID));
+  const newResolutions = { ...savedResolutions };
+
+  // Find all collisions (paths with >1 record)
+  const collisions = [];
+  for (const [filePath, records] of registry.entries()) {
+    if (records.length > 1) {
+      collisions.push({ filePath, records });
+    }
+  }
+
+  if (collisions.length === 0) return toDelete;
+
+  log.warn(`Found ${collisions.length} file path collision(s)`);
+
+  for (const { filePath, records } of collisions) {
+    // Same-entity duplicates are not cross-entity collisions — handled by UID naming
+    const entities = new Set(records.map(r => r.entity));
+    if (entities.size === 1) {
+      log.dim(`  Same-entity duplicates for "${filePath}" — will use UID naming`);
+      continue;
+    }
+
+    // Check if we have a stored resolution for this path
+    const saved = savedResolutions[filePath];
+    if (saved && records.some(r => r.record.UID === saved.keepUID)) {
+      // Auto-apply stored resolution
+      for (const r of records) {
+        if (r.record.UID !== saved.keepUID) {
+          toDelete.add(r.record.UID);
+        }
+      }
+      log.dim(`  Collision "${filePath}" → keeping ${saved.keepEntity} (saved preference)`);
+      continue;
+    }
+
+    // Check if any record in this collision is already pending deletion
+    const pendingRecord = records.find(r => pendingDeleteUIDs.has(r.record.UID));
+    if (pendingRecord) {
+      toDelete.add(pendingRecord.record.UID);
+      // Store as resolution for future clones
+      const keptRecord = records.find(r => r.record.UID !== pendingRecord.record.UID);
+      if (keptRecord) {
+        newResolutions[filePath] = { keepUID: keptRecord.record.UID, keepEntity: keptRecord.entity };
+      }
+      log.dim(`  Collision "${filePath}" → ${pendingRecord.record.UID} already staged for deletion`);
+      continue;
+    }
+
+    // Non-interactive mode: keep first, skip rest
+    if (options.yes) {
+      for (let i = 1; i < records.length; i++) {
+        toDelete.add(records[i].record.UID);
+      }
+      newResolutions[filePath] = { keepUID: records[0].record.UID, keepEntity: records[0].entity };
+      continue;
+    }
+
+    // Interactive resolution
+    const inquirer = (await import('inquirer')).default;
+
+    log.plain('');
+    log.warn(`Collision: ${records.length} records want to create "${filePath}"`);
+
+    const choices = records.map((r, idx) => {
+      const label = r.record.Name || r.record.Filename || r.record.UID;
+      return {
+        name: `[${r.entity}] ${label} (UID: ${r.record.UID})`,
+        value: idx,
+      };
+    });
+
+    const { keepIdx } = await inquirer.prompt([{
+      type: 'list',
+      name: 'keepIdx',
+      message: 'Which record should create this file?',
+      choices,
+    }]);
+
+    // Store resolution for future clones
+    newResolutions[filePath] = { keepUID: records[keepIdx].record.UID, keepEntity: records[keepIdx].entity };
+
+    // Mark others for deletion
+    for (let i = 0; i < records.length; i++) {
+      if (i !== keepIdx) {
+        toDelete.add(records[i].record.UID);
+      }
+    }
+  }
+
+  // Save resolutions for future clones
+  await saveCollisionResolutions(newResolutions);
+
+  return toDelete;
+}
+
+/**
+ * Stage deletion entries for rejected collision records.
+ * Prompts per-item for confirmation unless -y flag is set.
+ */
+async function stageCollisionDeletions(toDelete, appJson, options) {
+  if (toDelete.size === 0) return;
+
+  // Collect records to potentially stage
+  const toStage = [];
+  for (const [entityName, entries] of Object.entries(appJson.children)) {
+    if (!Array.isArray(entries)) continue;
+
+    for (const record of entries) {
+      if (!toDelete.has(record.UID)) continue;
+
+      // Find RowID
+      let rowId = record._id;
+      if (!rowId) {
+        const entityCap = entityName.charAt(0).toUpperCase() + entityName.slice(1);
+        rowId = record[`${entityCap}ID`];
+      }
+
+      if (!rowId) {
+        log.warn(`Cannot stage ${entityName} ${record.UID}: no RowID`);
+        continue;
+      }
+
+      const name = record.Name || record.Filename || record.UID;
+      toStage.push({ UID: record.UID, RowID: rowId, entity: entityName, name });
+    }
+  }
+
+  if (toStage.length === 0) return;
+
+  // Check which are already staged (skip re-prompting)
+  const sync = await loadSynchronize();
+  const alreadyStaged = new Set((sync.delete || []).map(e => e.UID));
+  const newItems = toStage.filter(item => !alreadyStaged.has(item.UID));
+
+  if (newItems.length === 0) {
+    log.dim(`  All ${toStage.length} collision rejection(s) already staged for deletion`);
+    return;
+  }
+
+  // Non-interactive mode: skip staging
+  if (options.yes) {
+    log.info(`Non-interactive mode: skipping deletion staging for ${newItems.length} rejected record(s)`);
+    return;
+  }
+
+  // Prompt per-item
+  log.info(`${newItems.length} rejected record(s) can be staged for deletion:`);
+  const inquirer = (await import('inquirer')).default;
+  let staged = 0;
+
+  for (const item of newItems) {
+    const { stage } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'stage',
+      message: `Stage [${item.entity}] "${item.name}" (UID: ${item.UID}) for deletion?`,
+      default: true,
+    }]);
+
+    if (stage) {
+      const expression = `RowID:del${item.RowID};entity:${item.entity}=true`;
+      await addDeleteEntry({ UID: item.UID, RowID: item.RowID, entity: item.entity, name: item.name, expression });
+      log.dim(`  Staged: ${item.entity} "${item.name}"`);
+      staged++;
+    } else {
+      log.dim(`  Skipped: ${item.entity} "${item.name}"`);
+    }
+  }
+
+  if (staged > 0) {
+    log.success(`${staged} record(s) staged in .dbo/synchronize.json`);
+    log.dim('  Run "dbo push" to delete from server');
+  }
+}
+
 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)')
@@ -165,6 +501,16 @@ export async function performClone(source, options = {}) {
   });
   log.dim('  Updated .dbo/config.json with app metadata');
 
+  // Detect and store ModifyKey for locked/production apps
+  const modifyKey = appJson.ModifyKey || null;
+  await saveAppModifyKey(modifyKey);
+  if (modifyKey) {
+    log.warn('');
+    log.warn('  ⚠  This app has a ModifyKey set (production/locked mode).');
+    log.warn('     You will be prompted to enter the ModifyKey before any push, input, add, content deploy, or deploy command.');
+    log.warn('');
+  }
+
   // Step 3: Update package.json
   await updatePackageJson(appJson, config);
 
@@ -194,20 +540,30 @@ export async function performClone(source, options = {}) {
     log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
   }
 
-  // Step 5: Process content → files + metadata
+  // 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);
+
+  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,
   );
 
-  // Step 5b: Process media → download binary files + metadata
+  // 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);
+    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)
@@ -396,7 +752,7 @@ async function updatePackageJson(appJson, config) {
  * Process content entries: write files + metadata, return reference map.
  * Returns array of { uid, metaPath } for app.json reference replacement.
  */
-async function processContentEntries(contents, structure, options, contentPlacement, serverTz) {
+async function processContentEntries(contents, structure, options, contentPlacement, serverTz, skipUIDs = new Set()) {
   if (!contents || contents.length === 0) return [];
 
   const refs = [];
@@ -410,6 +766,10 @@ async function processContentEntries(contents, structure, options, contentPlacem
   log.info(`Processing ${contents.length} content record(s)...`);
 
   for (const record of contents) {
+    if (skipUIDs.has(record.UID)) {
+      log.dim(`  Skipped ${record.Name || record.UID} (collision rejection)`);
+      continue;
+    }
     const ref = await processRecord('content', record, structure, options, usedNames, placementPreference, serverTz, bulkAction);
     if (ref) refs.push(ref);
   }
@@ -465,7 +825,6 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
   await mkdir(dirName, { recursive: true });
 
   const refs = [];
-  const usedNames = new Map();
   const bulkAction = { value: null };
   const config = await loadConfig();
 
@@ -614,11 +973,10 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       name = sanitizeFilename(String(record.UID || 'untitled'));
     }
 
-    // Deduplicate filenames
-    const nameKey = `${dirName}/${name}`;
-    const count = usedNames.get(nameKey) || 0;
-    usedNames.set(nameKey, count + 1);
-    const finalName = count > 0 ? `${name}-${count + 1}` : name;
+    // Include UID in filename to ensure uniqueness (multiple records can share the same name)
+    // Convention: <name>.<UID>.metadata.json — unless name === UID, then just <UID>.metadata.json
+    const uid = record.UID || 'untitled';
+    const finalName = name === uid ? uid : `${name}.${uid}`;
 
     const metaPath = join(dirName, `${finalName}.metadata.json`);
 
@@ -755,9 +1113,12 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
  * Process media entries: download binary files from server + create metadata.
  * Media uses Filename (not Name) and files are fetched via /api/media/{uid}.
  */
-async function processMediaEntries(mediaRecords, structure, options, config, appShortName, mediaPlacement, serverTz) {
+async function processMediaEntries(mediaRecords, structure, options, config, appShortName, mediaPlacement, serverTz, skipUIDs = new Set()) {
   if (!mediaRecords || mediaRecords.length === 0) return [];
 
+  // Track stale records (404s) for cleanup prompt
+  const staleRecords = [];
+
   // Determine if we can download (need a server connection)
   let canDownload = false;
   let client = null;
@@ -804,6 +1165,12 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
 
   for (const record of mediaRecords) {
     const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
+
+    if (skipUIDs.has(record.UID)) {
+      log.dim(`  Skipped ${filename} (collision rejection)`);
+      continue;
+    }
+
     const name = sanitizeFilename(filename.replace(/\.[^.]+$/, '')); // base name without extension
     const ext = (record.Extension || 'bin').toLowerCase();
 
@@ -869,7 +1236,14 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const fileKey = `${dir}/${name}.${ext}`;
     const fileCount = usedNames.get(fileKey) || 0;
     usedNames.set(fileKey, fileCount + 1);
-    const dedupName = fileCount > 0 ? `${name}-${fileCount + 1}` : name;
+    let dedupName;
+    if (fileCount > 0) {
+      // Duplicate name — include UID for uniqueness
+      const uid = record.UID || 'untitled';
+      dedupName = name === uid ? uid : `${name}.${uid}`;
+    } else {
+      dedupName = name;
+    }
     const finalFilename = `${dedupName}.${ext}`;
     // Metadata: use name.ext as base to avoid collisions between formats
     // e.g. KaTeX_SansSerif-Italic.woff.metadata.json vs KaTeX_SansSerif-Italic.woff2.metadata.json
@@ -954,11 +1328,26 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       log.success(`Downloaded ${filePath} (${sizeKB} KB)`);
       downloaded++;
     } catch (err) {
-      log.warn(`Failed to download ${filename}`);
-      log.dim(`  UID: ${record.UID}`);
-      log.dim(`  URL: /api/media/${record.UID}`);
-      if (record.FullPath) log.dim(`  FullPath: ${record.FullPath}`);
-      log.dim(`  Error: ${err.message}`);
+      // Check if error is 404 (stale record)
+      const is404 = /Download failed: 404/.test(err.message);
+
+      if (is404) {
+        log.warn(`Stale media: ${filename} (404 - file no longer exists)`);
+        staleRecords.push({
+          UID: record.UID,
+          RowID: record._id || record.MediaID,
+          filename,
+          fullPath: record.FullPath,
+          record,
+        });
+      } else {
+        log.warn(`Failed to download ${filename}`);
+        log.dim(`  UID: ${record.UID}`);
+        log.dim(`  URL: /api/media/${record.UID}`);
+        if (record.FullPath) log.dim(`  FullPath: ${record.FullPath}`);
+        log.dim(`  Error: ${err.message}`);
+      }
+
       failed++;
       continue; // Skip metadata if download failed
     }
@@ -987,6 +1376,41 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   }
 
   log.info(`Media: ${downloaded} downloaded, ${failed} failed`);
+
+  // Prompt for stale record cleanup
+  if (staleRecords.length > 0 && !options.yes) {
+    log.plain('');
+    log.info(`Found ${staleRecords.length} stale media record(s) (404 - files no longer exist on server)`);
+
+    const inquirer = (await import('inquirer')).default;
+    const { cleanup } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'cleanup',
+      message: `Stage these ${staleRecords.length} stale media records for deletion?`,
+      default: false, // Conservative default
+    }]);
+
+    if (cleanup) {
+      for (const stale of staleRecords) {
+        const expression = `RowID:del${stale.RowID};entity:media=true`;
+        await addDeleteEntry({
+          UID: stale.UID,
+          RowID: stale.RowID,
+          entity: 'media',
+          name: stale.filename,
+          expression,
+        });
+        log.dim(`  Staged: ${stale.filename}`);
+      }
+      log.success('Stale media records staged in .dbo/synchronize.json');
+      log.dim('  Run "dbo push" to delete from server');
+    } else {
+      log.info('Skipped stale media cleanup');
+    }
+  } else if (staleRecords.length > 0 && options.yes) {
+    log.info(`Non-interactive mode: skipping stale cleanup for ${staleRecords.length} record(s)`);
+  }
+
   return refs;
 }
 
@@ -1084,11 +1508,18 @@ async function processRecord(entityName, record, structure, options, usedNames,
 
   await mkdir(dir, { recursive: true });
 
-  // Deduplicate filenames
+  // Deduplicate filenames — use UID naming when duplicates exist
   const nameKey = `${dir}/${name}`;
   const count = usedNames.get(nameKey) || 0;
   usedNames.set(nameKey, count + 1);
-  const finalName = count > 0 ? `${name}-${count + 1}` : name;
+  let finalName;
+  if (count > 0) {
+    // Duplicate name — include UID for uniqueness
+    const uid = record.UID || 'untitled';
+    finalName = name === uid ? uid : `${name}.${uid}`;
+  } else {
+    finalName = name;
+  }
 
   // Write content file if Content column has data
   const contentValue = record.Content;
@@ -1307,8 +1738,8 @@ function decodeBase64Fields(obj) {
   // Process each property
   for (const [key, value] of Object.entries(obj)) {
     if (value && typeof value === 'object') {
-      // Check if it's a base64 encoded value
-      if (!Array.isArray(value) && value.encoding === 'base64' && typeof value.value === 'string') {
+      // Check if it's a base64 encoded value (handles both value: string and value: null)
+      if (!Array.isArray(value) && value.encoding === 'base64') {
         // Decode using existing resolveContentValue function
         obj[key] = resolveContentValue(value);
       } else {

package/src/commands/content.js

@@ -5,6 +5,7 @@ import { DboClient } from '../lib/client.js';
 import { buildInputBody } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { saveToDisk } from '../lib/save-to-disk.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 function collect(value, previous) {
@@ -28,16 +29,38 @@ const deployCmd = new Command('deploy')
   .argument('<filepath>', 'Local file path')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
   .action(async (uid, filepath, options) => {
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+
       const extraParams = { '_confirm': options.confirm };
       if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
-      const body = await buildInputBody([`RowUID:${uid};column:content.Content@${filepath}`], extraParams);
-      const result = await client.postUrlEncoded('/api/input/submit', body);
+      if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
+
+      const dataExprs = [`RowUID:${uid};column:content.Content@${filepath}`];
+      let body = await buildInputBody(dataExprs, extraParams);
+      let result = await client.postUrlEncoded('/api/input/submit', body);
+
+      // Reactive ModifyKey retry
+      if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+        const retryMK = await handleModifyKeyError();
+        if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+        extraParams['_modify_key'] = retryMK.modifyKey;
+        body = await buildInputBody(dataExprs, extraParams);
+        result = await client.postUrlEncoded('/api/input/submit', body);
+      }
+
       formatResponse(result, { json: options.json });
       if (!result.successful) process.exit(1);
     } catch (err) {

package/src/commands/deploy.js

@@ -3,6 +3,7 @@ import { readFile } from 'fs/promises';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 const MANIFEST_FILE = 'dbo.deploy.json';
@@ -13,6 +14,7 @@ export const deployCommand = new Command('deploy')
   .option('--all', 'Deploy all entries in the manifest')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
@@ -51,6 +53,14 @@ export const deployCommand = new Command('deploy')
         process.exit(1);
       }
 
+      // ModifyKey guard — check once before any submissions
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      let activeModifyKey = modifyKeyResult.modifyKey;
+
       for (const [entryName, entry] of entries) {
         if (!entry) {
           log.warn(`Skipping unknown deployment: ${entryName}`);
@@ -71,8 +81,21 @@ export const deployCommand = new Command('deploy')
 
         const extraParams = { '_confirm': options.confirm };
         if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
-        const body = await buildInputBody([`RowUID:${uid};column:${entity}.${column}@${file}`], extraParams);
-        const result = await client.postUrlEncoded('/api/input/submit', body);
+        if (activeModifyKey) extraParams['_modify_key'] = activeModifyKey;
+
+        const dataExprs = [`RowUID:${uid};column:${entity}.${column}@${file}`];
+        let body = await buildInputBody(dataExprs, extraParams);
+        let result = await client.postUrlEncoded('/api/input/submit', body);
+
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); break; }
+          activeModifyKey = retryMK.modifyKey;
+          extraParams['_modify_key'] = activeModifyKey;
+          body = await buildInputBody(dataExprs, extraParams);
+          result = await client.postUrlEncoded('/api/input/submit', body);
+        }
 
         if (result.successful) {
           log.success(`${entryName} deployed`);

package/src/commands/input.js

@@ -4,6 +4,7 @@ import { buildInputBody, parseFileArg, checkSubmitErrors } from '../lib/input-pa
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { loadAppConfig } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 function collect(value, previous) {
@@ -16,6 +17,7 @@ export const inputCommand = new Command('input')
   .option('-f, --file <field=@path>', 'File attachment for multipart upload (repeatable)', collect, [])
   .option('-C, --confirm <value>', 'Commit changes: true (default) or false for validation only', 'true')
   .option('--ticket <id>', 'Override ticket ID (_OverrideTicketID)')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--login', 'Auto-login user created by this submission')
   .option('--transactional', 'Use transactional processing')
   .option('--json', 'Output raw JSON response')
@@ -45,6 +47,14 @@ export const inputCommand = new Command('input')
         }
       }
 
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
+
       // Check if data expressions include AppID; if not and config has one, prompt
       const allDataText = options.data.join(' ');
       const hasAppId = /\.AppID[=@]/.test(allDataText) || /AppID=/.test(allDataText);
@@ -93,6 +103,14 @@ export const inputCommand = new Command('input')
         const files = options.file.map(parseFileArg);
         let result = await client.postMultipart('/api/input/submit', fields, files);
 
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+          fields['_modify_key'] = retryMK.modifyKey;
+          result = await client.postMultipart('/api/input/submit', fields, files);
+        }
+
         // Retry with prompted params if needed (ticket, user, repo mismatch)
         const retryResult = await checkSubmitErrors(result);
         if (retryResult) {
@@ -112,6 +130,15 @@ export const inputCommand = new Command('input')
         let body = await buildInputBody(options.data, extraParams);
         let result = await client.postUrlEncoded('/api/input/submit', body);
 
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+          extraParams['_modify_key'] = retryMK.modifyKey;
+          body = await buildInputBody(options.data, extraParams);
+          result = await client.postUrlEncoded('/api/input/submit', body);
+        }
+
         // Retry with prompted params if needed (ticket, user, repo mismatch)
         const retryResult = await checkSubmitErrors(result);
         if (retryResult) {

package/src/commands/push.js

@@ -8,6 +8,7 @@ import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
 import { loadConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { findMetadataFiles } from '../lib/diff.js';
 import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
@@ -18,6 +19,7 @@ export const pushCommand = new Command('push')
   .argument('<path>', 'File or directory to push')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--meta-only', 'Only push metadata changes, skip file content')
   .option('--content-only', 'Only push file content, skip metadata columns')
   .option('-y, --yes', 'Auto-accept all prompts (path refactoring, etc.)')
@@ -29,15 +31,23 @@ export const pushCommand = new Command('push')
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
+      // ModifyKey guard — check once before any submissions
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      const modifyKey = modifyKeyResult.modifyKey;
+
       // Process pending deletions from synchronize.json
-      await processPendingDeletes(client, options);
+      await processPendingDeletes(client, options, modifyKey);
 
       const pathStat = await stat(targetPath);
 
       if (pathStat.isDirectory()) {
-        await pushDirectory(targetPath, client, options);
+        await pushDirectory(targetPath, client, options, modifyKey);
       } else {
-        await pushSingleFile(targetPath, client, options);
+        await pushSingleFile(targetPath, client, options, modifyKey);
       }
     } catch (err) {
       formatError(err);
@@ -48,7 +58,7 @@ export const pushCommand = new Command('push')
 /**
  * Process pending delete entries from .dbo/synchronize.json
  */
-async function processPendingDeletes(client, options) {
+async function processPendingDeletes(client, options, modifyKey = null) {
   const sync = await loadSynchronize();
   if (!sync.delete || sync.delete.length === 0) return;
 
@@ -62,6 +72,7 @@ async function processPendingDeletes(client, options) {
 
     const extraParams = { '_confirm': options.confirm || 'true' };
     if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+    if (modifyKey) extraParams['_modify_key'] = modifyKey;
 
     const body = await buildInputBody([entry.expression], extraParams);
 
@@ -69,23 +80,33 @@ async function processPendingDeletes(client, options) {
       const result = await client.postUrlEncoded('/api/input/submit', body);
 
       // Retry with prompted params if needed
-      const retryResult = await checkSubmitErrors(result);
-      if (retryResult) {
-        if (retryResult.skipRecord || retryResult.skipAll) {
+      const errorResult = await checkSubmitErrors(result);
+      if (errorResult) {
+        if (errorResult.skipRecord) {
           log.warn(`  Skipping deletion of "${entry.name}"`);
           remaining.push(entry);
           continue;
         }
-        const params = retryResult.retryParams || retryResult;
+        if (errorResult.skipAll) {
+          log.warn(`  Skipping deletion of "${entry.name}" and all remaining`);
+          remaining.push(entry);
+          // Push all remaining entries too
+          const currentIdx = sync.delete.indexOf(entry);
+          for (let i = currentIdx + 1; i < sync.delete.length; i++) {
+            remaining.push(sync.delete[i]);
+          }
+          break;
+        }
+        const params = errorResult.retryParams || errorResult;
         Object.assign(extraParams, params);
         const retryBody = await buildInputBody([entry.expression], extraParams);
-        const retryResult = await client.postUrlEncoded('/api/input/submit', retryBody);
-        if (retryResult.successful) {
+        const retryResponse = await client.postUrlEncoded('/api/input/submit', retryBody);
+        if (retryResponse.successful) {
           log.success(`  Deleted "${entry.name}" from server`);
           deletedUids.push(entry.UID);
         } else {
           log.error(`  Failed to delete "${entry.name}"`);
-          formatResponse(retryResult, { json: options.json, jq: options.jq });
+          formatResponse(retryResponse, { json: options.json, jq: options.jq });
           remaining.push(entry);
         }
       } else if (result.successful) {
@@ -119,7 +140,7 @@ async function processPendingDeletes(client, options) {
 /**
  * Push a single file using its companion .metadata.json
  */
-async function pushSingleFile(filePath, client, options) {
+async function pushSingleFile(filePath, client, options, modifyKey = null) {
   // Find the metadata file
   const dir = dirname(filePath);
   const base = basename(filePath, extname(filePath));
@@ -133,13 +154,13 @@ async function pushSingleFile(filePath, client, options) {
     process.exit(1);
   }
 
-  await pushFromMetadata(meta, metaPath, client, options);
+  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey);
 }
 
 /**
  * Push all records found in a directory (recursive)
  */
-async function pushDirectory(dirPath, client, options) {
+async function pushDirectory(dirPath, client, options, modifyKey = null) {
   const metaFiles = await findMetadataFiles(dirPath);
 
   if (metaFiles.length === 0) {
@@ -151,7 +172,6 @@ async function pushDirectory(dirPath, client, options) {
 
   // Load baseline for delta detection
   const baseline = await loadAppJsonBaseline();
-  const config = await loadConfig();
 
   if (!baseline) {
     log.warn('No .app.json baseline found — performing full push (run "dbo clone" to enable delta sync)');
@@ -205,7 +225,7 @@ async function pushDirectory(dirPath, client, options) {
     let changedColumns = null;
     if (baseline) {
       try {
-        changedColumns = await detectChangedColumns(metaPath, baseline, config);
+        changedColumns = await detectChangedColumns(metaPath, baseline);
         if (changedColumns.length === 0) {
           log.dim(`  Skipping ${basename(metaPath)} — no changes detected`);
           skipped++;
@@ -252,7 +272,7 @@ async function pushDirectory(dirPath, client, options) {
 
   for (const item of toPush) {
     try {
-      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns);
+      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey);
       if (success) {
         succeeded++;
         successfulPushes.push(item);
@@ -286,7 +306,7 @@ async function pushDirectory(dirPath, client, options) {
  * @param {string[]|null} changedColumns - Optional array of changed column names (for delta sync)
  * @returns {Promise<boolean>} - True if push succeeded
  */
-async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null) {
+async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null, modifyKey = null) {
   const uid = meta.UID || meta._id;
   const entity = meta._entity;
   const contentCols = new Set(meta._contentColumns || []);
@@ -350,10 +370,20 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
 
   let body = await buildInputBody(dataExprs, extraParams);
   let result = await client.postUrlEncoded('/api/input/submit', body);
 
+  // Reactive ModifyKey retry — server rejected because key wasn't set locally
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return false; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
   // Retry with prompted params if needed (ticket, user, repo mismatch)
   const retryResult = await checkSubmitErrors(result);
   if (retryResult) {

package/src/lib/config.js

@@ -181,9 +181,10 @@ export async function loadAppConfig() {
       AppUID: config.AppUID || null,
       AppName: config.AppName || null,
       AppShortName: config.AppShortName || null,
+      AppModifyKey: config.AppModifyKey || null,
     };
   } catch {
-    return { AppID: null, AppUID: null, AppName: null, AppShortName: null };
+    return { AppID: null, AppUID: null, AppName: null, AppShortName: null, AppModifyKey: null };
   }
 }
 
@@ -286,6 +287,37 @@ export async function loadEntityContentExtractions(entityKey) {
   }
 }
 
+/**
+ * Save collision resolutions to .dbo/config.json.
+ * Maps file paths to the UID of the record the user chose to keep.
+ *
+ * @param {Object} resolutions - { "Bins/app/file.css": { keepUID: "abc", keepEntity: "content" } }
+ */
+export async function saveCollisionResolutions(resolutions) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  existing.CollisionResolutions = resolutions;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load collision resolutions from .dbo/config.json.
+ *
+ * @returns {Object} - { "Bins/app/file.css": { keepUID: "abc", keepEntity: "content" } }
+ */
+export async function loadCollisionResolutions() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    return config.CollisionResolutions || {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Save user profile fields (FirstName, LastName, Email) into credentials.json.
  */
@@ -497,6 +529,32 @@ export async function getAllPluginScopes() {
   return result;
 }
 
+// ─── AppModifyKey ─────────────────────────────────────────────────────────
+
+/**
+ * Save AppModifyKey to .dbo/config.json.
+ * Pass null to remove the key (e.g. when server no longer has one).
+ */
+export async function saveAppModifyKey(modifyKey) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (modifyKey != null) existing.AppModifyKey = modifyKey;
+  else delete existing.AppModifyKey;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load AppModifyKey from .dbo/config.json.
+ * Returns the key string or null if not set.
+ */
+export async function loadAppModifyKey() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    return JSON.parse(raw).AppModifyKey || null;
+  } catch { return null; }
+}
+
 // ─── Gitignore ────────────────────────────────────────────────────────────
 
 /**

package/src/lib/delta.js

@@ -84,10 +84,9 @@ export async function compareFileContent(filePath, baselineValue) {
  *
  * @param {string} metaPath - Path to metadata.json file
  * @param {Object} baseline - The baseline JSON
- * @param {Object} config - CLI config (for resolving file paths)
  * @returns {Promise<string[]>} - Array of changed column names
  */
-export async function detectChangedColumns(metaPath, baseline, config) {
+export async function detectChangedColumns(metaPath, baseline) {
   // Load current metadata
   const metaRaw = await readFile(metaPath, 'utf8');
   const metadata = JSON.parse(metaRaw);
@@ -160,27 +159,24 @@ function shouldSkipColumn(columnName) {
 }
 
 /**
- * Check if a value is a @reference object.
+ * Check if a value is a @reference (string starting with @).
  *
  * @param {*} value - Value to check
  * @returns {boolean} - True if reference
  */
 function isReference(value) {
-  return value &&
-         typeof value === 'object' &&
-         !Array.isArray(value) &&
-         value['@reference'] !== undefined;
+  return typeof value === 'string' && value.startsWith('@');
 }
 
 /**
  * Resolve a @reference path to absolute file path.
  *
- * @param {Object} reference - Reference object with @reference property
+ * @param {string} reference - Reference string starting with @ (e.g., "@file.html")
  * @param {string} baseDir - Base directory containing metadata
  * @returns {string} - Absolute file path
  */
 function resolveReferencePath(reference, baseDir) {
-  const refPath = reference['@reference'];
+  const refPath = reference.substring(1); // Strip leading @
   return join(baseDir, refPath);
 }
 

package/src/lib/input-parser.js

@@ -116,7 +116,8 @@ export async function checkSubmitErrors(result) {
   const allText = messages.filter(m => typeof m === 'string').join(' ');
 
   // --- Ticket error detection (new interactive handling) ---
-  const hasTicketError = allText.includes('ticket_error');
+  // Match ticket_error, ticket_lookup_error, and similar variants
+  const hasTicketError = allText.includes('ticket_error') || allText.includes('ticket_lookup_error');
   const hasRepoMismatch = allText.includes('repo_mismatch');
 
   if (hasTicketError) {

package/src/lib/modify-key.js

@@ -0,0 +1,96 @@
+import { loadAppModifyKey, saveAppModifyKey } from './config.js';
+import { log } from './logger.js';
+
+/**
+ * Pre-submission ModifyKey guard.
+ * - If options.modifyKey flag is set, it takes precedence — no prompt, no config check.
+ * - Returns { modifyKey: null } if no key is set in config (no-op).
+ * - Prompts user to type the key; returns { modifyKey: string } on match.
+ * - Returns { modifyKey: null, cancel: true } on mismatch or cancel.
+ */
+export async function checkModifyKey(options = {}) {
+  // --modifyKey flag takes precedence (mirrors --ticket / --confirm behavior)
+  if (options.modifyKey) return { modifyKey: options.modifyKey, cancel: false };
+
+  const storedKey = await loadAppModifyKey();
+  if (!storedKey) return { modifyKey: null, cancel: false };
+
+  log.warn('');
+  log.warn('  ⚠  This app is locked (production mode). A ModifyKey is required to submit changes.');
+  log.warn('');
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'This app has a ModifyKey set. How would you like to proceed?',
+    choices: [
+      { name: 'Enter the ModifyKey to proceed', value: 'enter' },
+      { name: 'Cancel submission', value: 'cancel' },
+    ],
+  }]);
+
+  if (action === 'cancel') return { modifyKey: null, cancel: true };
+
+  const { enteredKey } = await inquirer.prompt([{
+    type: 'input',
+    name: 'enteredKey',
+    message: 'ModifyKey:',
+  }]);
+
+  const key = enteredKey.trim();
+  if (!key) {
+    log.error('  No ModifyKey entered. Submission cancelled.');
+    return { modifyKey: null, cancel: true };
+  }
+
+  return { modifyKey: key, cancel: false };
+}
+
+/**
+ * Detects whether a server response error message requires a ModifyKey.
+ * Server error format: "Error:The '<app>' app (UID=...) has a ModifyKey – ..."
+ */
+export function isModifyKeyError(responseMessage) {
+  return typeof responseMessage === 'string' && responseMessage.includes('has a ModifyKey');
+}
+
+/**
+ * Reactive ModifyKey handler — called after a submission fails with a ModifyKey error.
+ * Prompts the user to enter the key, saves it to config, and returns it for retry.
+ * Returns { modifyKey: string } on success or { modifyKey: null, cancel: true } on cancel.
+ */
+export async function handleModifyKeyError() {
+  log.warn('');
+  log.warn('  ⚠  This app requires a ModifyKey. The key has not been set locally (try re-running `dbo clone`).');
+  log.warn('');
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'A ModifyKey is required. How would you like to proceed?',
+    choices: [
+      { name: 'Enter the ModifyKey to retry', value: 'enter' },
+      { name: 'Cancel submission', value: 'cancel' },
+    ],
+  }]);
+
+  if (action === 'cancel') return { modifyKey: null, cancel: true };
+
+  const { enteredKey } = await inquirer.prompt([{
+    type: 'input',
+    name: 'enteredKey',
+    message: 'ModifyKey:',
+  }]);
+
+  const key = enteredKey.trim();
+  if (!key) {
+    log.error('  No ModifyKey entered. Submission cancelled.');
+    return { modifyKey: null, cancel: true };
+  }
+
+  await saveAppModifyKey(key);
+  log.info('  ModifyKey saved to .dbo/config.json for future use.');
+  return { modifyKey: key, cancel: false };
+}