@dboio/cli 0.19.7 → 0.20.3

package/src/commands/clone.js

@@ -3,18 +3,18 @@ import { readFile, writeFile, appendFile, mkdir, access, readdir, rename, stat,
 import { join, basename, extname, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, updateConfigUserMedia, 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, loadRootContentFiles } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, updateConfigUserMedia, loadClonePlacement, saveClonePlacement, ensureGitignore, DEFAULT_GITIGNORE_ENTRIES, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement, loadRootContentFiles } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, SCAFFOLD_DIRS, ENTITY_DIR_NAMES, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES, EXTENSION_DESCRIPTORS_DIR, EXTENSION_UNSUPPORTED_DIR, DOCUMENTATION_DIR, buildDescriptorMapping, saveDescriptorMapping, loadDescriptorMapping, resolveExtensionSubDir, resolveEntityDirPath, resolveFieldValue } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { buildUidFilename, buildContentFileName, buildMetaFilename, isMetadataFile, parseMetaFilename, stripUidFromFilename, hasUidInFilename } from '../lib/filenames.js';
 import { setFileTimestamps, parseServerDate } from '../lib/timestamps.js';
 import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge, isDiffable, loadBaselineForComparison, resetBaselineCache, findMetadataFiles } from '../lib/diff.js';
-import { loadIgnore } from '../lib/ignore.js';
+import { loadIgnore, getDefaultFileContent as getDboignoreDefaultContent } from '../lib/ignore.js';
 import { checkDomainChange } from '../lib/domain-guard.js';
 import { applyTrashIcon, ensureTrashIcon, tagProjectFiles } from '../lib/tagging.js';
 import { loadMetadataSchema, saveMetadataSchema, getTemplateCols, setTemplateCols, buildTemplateFromCloneRecord, generateMetadataFromSchema, parseReferenceExpression, mergeDescriptorSchemaFromDependencies } from '../lib/metadata-schema.js';
 import { fetchSchema, loadSchema, saveSchema, isSchemaStale } from '../lib/schema.js';
-import { appMetadataPath } from '../lib/config.js';
+import { appMetadataPath, baselinePath, metadataSchemaPath } from '../lib/config.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 import { upsertDeployEntry } from '../lib/deploy-config.js';
 import { syncDependencies, parseDependenciesColumn } from '../lib/dependencies.js';
@@ -76,6 +76,37 @@ async function fileExists(path) {
   try { await access(path); return true; } catch { return false; }
 }
 
+/**
+ * Resolve a metadata file path with collision detection.
+ * Content records are processed before output, so they naturally claim the unsuffixed
+ * name. This function ensures output (and any late-arriving entity) gets a numbered
+ * suffix when the clean name is already owned by a different UID.
+ *
+ * Algorithm: try name.metadata.json, then name-1.metadata.json, name-2.metadata.json, …
+ * until we find a slot that either doesn't exist or is owned by the same UID.
+ *
+ * @param {string} dir         - Directory to check
+ * @param {string} naturalBase - Natural base name (no .metadata.json suffix)
+ * @param {string} uid         - UID of the record being written
+ * @returns {Promise<string>}  - Absolute path to use for the metadata file
+ */
+async function resolveMetaCollision(dir, naturalBase, uid) {
+  for (let i = 0; i < 1000; i++) {
+    const candidate = i === 0
+      ? `${naturalBase}.metadata.json`
+      : `${naturalBase}-${i}.metadata.json`;
+    const fullPath = join(dir, candidate);
+    try {
+      const existing = JSON.parse(await readFile(fullPath, 'utf8'));
+      if (!existing.UID || existing.UID === uid) return fullPath; // same or new record
+      // Slot owned by a different UID — try next
+    } catch {
+      return fullPath; // file doesn't exist — use it
+    }
+  }
+  return join(dir, `${naturalBase}.metadata.json`); // fallback (should never reach here)
+}
+
 const WILL_DELETE_PREFIX = '__WILL_DELETE__';
 
 function isWillDeleteFile(filename) {
@@ -219,6 +250,114 @@ export async function detectAndTrashOrphans(appJson, ig, sync, options) {
   }
 }
 
+/**
+ * Use the explicit `appJson.deleted` map (returned by the server in delta/baseline responses)
+ * to find and trash local files for records the server has deleted.
+ *
+ * Unlike detectAndTrashOrphans() which diffs all local UIDs against all server UIDs,
+ * this function is authoritative: if the server says a UID was deleted, it moves the
+ * local files immediately — no full UID scan needed. This makes it safe to call in
+ * pull/delta mode where appJson.children may only contain changed records.
+ *
+ * @param {object} appJson  - App JSON possibly containing a `deleted` map
+ * @param {import('ignore').Ignore} ig - Ignore instance for findMetadataFiles
+ * @param {object} sync     - Parsed synchronize.json { delete, edit, add }
+ * @param {object} options  - Clone options
+ */
+export async function trashServerDeletedRecords(appJson, ig, sync, options) {
+  if (options.entityFilter) return;
+  if (!appJson?.deleted || typeof appJson.deleted !== 'object') return;
+
+  // Build set of UIDs to trash from all entities in deleted map
+  const deletedUids = new Map(); // uid → { entity, name }
+  for (const [entity, entries] of Object.entries(appJson.deleted)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry?.UID) {
+        deletedUids.set(String(entry.UID), { entity, name: entry.Name || entry.UID });
+      }
+    }
+  }
+
+  if (deletedUids.size === 0) return;
+
+  // UIDs already queued for deletion in synchronize.json — skip them
+  const stagedDeleteUids = new Set(
+    (sync.delete || []).map(e => e.UID).filter(Boolean).map(String)
+  );
+
+  const metaFiles = await findMetadataFiles(process.cwd(), ig);
+  if (metaFiles.length === 0) return;
+
+  const trashDir = join(process.cwd(), 'trash');
+  const toTrash = [];
+
+  for (const metaPath of metaFiles) {
+    let meta;
+    try {
+      meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!meta.UID) continue;
+    const uid = String(meta.UID);
+    if (!deletedUids.has(uid)) continue;
+    if (stagedDeleteUids.has(uid)) continue;
+
+    const metaDir = dirname(metaPath);
+    const filesToMove = [metaPath];
+
+    for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
+      const ref = meta[col];
+      if (ref && String(ref).startsWith('@')) {
+        const refName = String(ref).substring(1);
+        const companionPath = refName.startsWith('/')
+          ? join(process.cwd(), refName)
+          : join(metaDir, refName);
+        if (await fileExists(companionPath)) filesToMove.push(companionPath);
+      }
+    }
+
+    if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+      const refName = String(meta._mediaFile).substring(1);
+      const mediaPath = refName.startsWith('/')
+        ? join(process.cwd(), refName)
+        : join(metaDir, refName);
+      if (await fileExists(mediaPath)) filesToMove.push(mediaPath);
+    }
+
+    const { entity } = deletedUids.get(uid);
+    toTrash.push({ metaPath, uid, entity, filesToMove });
+  }
+
+  if (toTrash.length === 0) return;
+
+  await mkdir(trashDir, { recursive: true });
+
+  let trashed = 0;
+  for (const { metaPath, uid, entity, filesToMove } of toTrash) {
+    log.dim(`  Trashed (server deleted): ${basename(metaPath)} (${entity}:${uid})`);
+    for (const filePath of filesToMove) {
+      const destBase = basename(filePath);
+      let destPath = join(trashDir, destBase);
+      try { await stat(destPath); destPath = `${destPath}.${Date.now()}`; } catch {}
+      try {
+        await rename(filePath, destPath);
+        trashed++;
+      } catch (err) {
+        log.warn(`  Could not trash: ${filePath} — ${err.message}`);
+      }
+    }
+  }
+
+  if (trashed > 0) {
+    await ensureTrashIcon(trashDir);
+    log.plain('');
+    log.warn(`Moved ${toTrash.length} server-deleted record(s) to trash`);
+  }
+}
+
 /**
  * Resolve a content Path to a directory under Bins/.
  *
@@ -322,8 +461,9 @@ export function resolveRecordPaths(entityName, record, structure, placementPref)
   const uid = String(record.UID || record._id || 'untitled');
   // Companion: natural name, no UID
   const filename = sanitizeFilename(buildContentFileName(record, uid));
-  // Metadata: name.metadata~uid.json
-  const metaPath = join(dir, buildMetaFilename(name, uid));
+  // Metadata: filename.metadata.json (includes extension to avoid collisions between records
+  // with the same Name but different Extension, e.g. codeTest.js vs codeTest.css)
+  const metaPath = join(dir, buildMetaFilename(filename));
 
   return { dir, filename, metaPath };
 }
@@ -352,10 +492,9 @@ export function resolveMediaPaths(record, structure) {
   dir = dir.replace(/^\/+|\/+$/g, '');
   if (!dir) dir = BINS_DIR;
 
-  // Metadata: name.ext.metadata~uid.json
-  const uid = String(record.UID || record._id || 'untitled');
+  // Metadata: name.ext.metadata.json
   const naturalMediaBase = `${name}.${ext}`;
-  const metaPath = join(dir, buildMetaFilename(naturalMediaBase, uid));
+  const metaPath = join(dir, buildMetaFilename(naturalMediaBase));
 
   return { dir, filename: companionFilename, metaPath };
 }
@@ -397,8 +536,7 @@ export function resolveEntityDirPaths(entityName, record, dirName) {
     name = sanitizeFilename(String(record.UID || 'untitled'));
   }
 
-  const uid = record.UID || 'untitled';
-  const metaPath = join(dirName, buildMetaFilename(name, uid));
+  const metaPath = join(dirName, buildMetaFilename(name));
   return { dir: dirName, name, metaPath };
 }
 
@@ -1197,11 +1335,42 @@ export async function performClone(source, options = {}) {
     }
   }
 
+  // Save AppShortName to config before writing the metadata schema so that
+  // metadataSchemaPath() resolves to <shortname>.metadata_schema.json rather
+  // than falling back to the generic app.metadata_schema.json.  Without this,
+  // processExtensionEntries() later loads null (wrong file) and descriptor
+  // sub-directories + companion @reference entries are lost.
+  if (!options.pullMode && appJson?.ShortName) {
+    // If the app's ShortName changed, rename the .app/ files that are keyed by it
+    // before updating config so the old paths can still be resolved.
+    const oldShortName = config.AppShortName;
+    const newShortName = appJson.ShortName;
+    if (oldShortName && oldShortName !== newShortName) {
+      const oldBaseline = await baselinePath();
+      const oldAppMeta = await appMetadataPath();
+      const oldSchema  = await metadataSchemaPath();
+      await updateConfigWithApp({ AppShortName: newShortName });
+      const newBaseline = await baselinePath();
+      const newAppMeta  = await appMetadataPath();
+      const newSchema   = await metadataSchemaPath();
+      for (const [oldPath, newPath] of [[oldBaseline, newBaseline], [oldAppMeta, newAppMeta], [oldSchema, newSchema]]) {
+        try { await access(oldPath); await rename(oldPath, newPath); log.dim(`  Renamed ${basename(oldPath)} → ${basename(newPath)}`); } catch { /* file absent, nothing to rename */ }
+      }
+    } else {
+      await updateConfigWithApp({ AppShortName: newShortName });
+    }
+  }
+
   // Regenerate metadata_schema.json for any new entity types
   if (schema) {
     const existing = await loadMetadataSchema();
     const updated = generateMetadataFromSchema(schema, existing ?? {});
     await saveMetadataSchema(updated);
+    // Remove orphaned app.metadata_schema.json left by previous runs that wrote
+    // the schema before AppShortName was saved (entity entries are regenerated above).
+    if (appJson?.ShortName && appJson.ShortName !== 'app') {
+      try { await unlink(join('.app', 'app.metadata_schema.json')); } catch { /* not present */ }
+    }
   }
 
   // Domain change detection
@@ -1222,7 +1391,7 @@ export async function performClone(source, options = {}) {
 
   // Ensure sensitive files are gitignored (skip for dependency checkouts — not user projects)
   if (!isDependencyCheckout()) {
-    await ensureGitignore(['.app/credentials.json', '.app/cookies.txt', '.app/ticketing.local.json', '.app/scripts.local.json', '.app/errors.log', 'app_dependencies/']);
+    await ensureGitignore(DEFAULT_GITIGNORE_ENTRIES);
   }
 
   // Step 2: Update .app/config.json (skip in pull mode — config already set)
@@ -1415,7 +1584,7 @@ export async function performClone(source, options = {}) {
 
   // Step 5a: Write root content files (manifest.json, CLAUDE.md, README.md, etc.) to project root.
   // Also fixes the duplicate bug: relocates companions from lib/bins/app/ to root and rewrites metadata.
-  if ((!entityFilter || entityFilter.has('content')) && !isDependencyCheckout()) {
+  if (!entityFilter || entityFilter.has('content')) {
     await writeRootContentFiles(appJson, contentRefs);
   }
 
@@ -1482,6 +1651,9 @@ export async function performClone(source, options = {}) {
   if (!entityFilter) {
     const ig = await loadIgnore();
     const sync = await loadSynchronize();
+    // Use explicit deleted list from server first (authoritative, works in delta/pull mode)
+    await trashServerDeletedRecords(appJson, ig, sync, { ...options, entityFilter });
+    // Fall back to full UID diff for records absent from server but not in deleted list
     await detectAndTrashOrphans(appJson, ig, sync, { ...options, entityFilter });
   }
 
@@ -1978,14 +2150,15 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     }
 
     // Resolve name collisions: second+ record with same name gets -1, -2, etc.
+    // Use case-insensitive key to prevent companion file collisions on case-insensitive filesystems.
     const uid = record.UID || 'untitled';
-    const nameKey = name;
+    const nameKey = name.toLowerCase();
     const count = usedNames.get(nameKey) || 0;
     usedNames.set(nameKey, count + 1);
     if (count > 0) name = `${name}-${count}`;
 
-    // Metadata: name.metadata~uid.json; companion files use natural name
-    const metaPath = join(dirName, buildMetaFilename(name, uid));
+    // Metadata: name.metadata.json; companion files use natural name
+    const metaPath = join(dirName, buildMetaFilename(name));
 
     // Legacy detection: rename old-format metadata files to new convention
     const legacyDotMetaPath = join(dirName, `${name}.${uid}.metadata.json`);
@@ -2031,7 +2204,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     // Skip __WILL_DELETE__-prefixed files — treat as "no existing file"
     const willDeleteEntityMeta = join(dirName, `${WILL_DELETE_PREFIX}${basename(metaPath)}`);
     const entityMetaExists = await fileExists(metaPath) && !await fileExists(willDeleteEntityMeta);
-    if (entityMetaExists && !options.yes && !hasNewExtractions) {
+    if (entityMetaExists && !options.yes && !options.force && !hasNewExtractions) {
       if (bulkAction.value === 'skip_all') {
         log.dim(`  Skipped ${name}`);
         refs.push({ uid: record.UID, metaPath });
@@ -2217,7 +2390,7 @@ function parseFormControlCode(string5) {
     if (codeStr) {
       for (const pair of codeStr.split(',')) {
         const [col, ext] = pair.split('|');
-        if (col?.trim() && ext?.trim()) colToExt.set(col.trim(), ext.trim().toLowerCase());
+        if (col?.trim()) colToExt.set(col.trim(), ext?.trim().toLowerCase() || 'md');
       }
     }
     const titleStr = params.get('form-control-title');
@@ -2284,9 +2457,10 @@ async function buildDescriptorPrePass(extensionEntries, structure, metadataSchem
     const { colToExt, colToTitle } = parseFormControlCode(string5);
     if (colToExt.size === 0) continue;
 
-    // Only populate if no entry already exists for this descriptor
+    // Only skip if the existing entry already has @reference expressions;
+    // plain-column entries (seeded without form-control-code) should be overwritten
     const existing = getTemplateCols(metadataSchema, 'extension', descriptor);
-    if (existing) continue;
+    if (existing?.some(e => e.includes('@reference'))) continue;
 
     const refEntries = [];
     for (const [col, ext] of colToExt) {
@@ -2469,8 +2643,6 @@ function guessExtensionForDescriptor(descriptor, columnName) {
  * @returns {Promise<'inline'|'root'>}
  */
 async function resolveDocumentationPlacement(options) {
-  if (options.yes) return 'inline';
-
   const saved = await loadExtensionDocumentationMDPlacement();
   if (saved && !options.force && !options.configure) {
     log.dim(`  Documentation MD placement: ${saved} (saved)`);
@@ -2478,7 +2650,7 @@ async function resolveDocumentationPlacement(options) {
   }
 
   let placement;
-  if (options.configure) {
+  if (options.configure && !options.yes) {
     const inquirer = (await import('inquirer')).default;
     ({ placement } = await inquirer.prompt([{
       type: 'list', name: 'placement',
@@ -2520,7 +2692,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
   log.info(`Processing ${entries.length} extension record(s)...`);
 
   // Step A: Pre-pass — build mapping + create directories
-  const metadataSchema = await loadMetadataSchema();
+  const metadataSchema = (await loadMetadataSchema()) ?? {};
   const mapping = await buildDescriptorPrePass(entries, structure, metadataSchema);
 
   // Clear documentation preferences when --force is used with --documentation-only
@@ -2568,12 +2740,19 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
   }
 
   // Step D: Write files, one group at a time
+  // descriptor_definition must be written before dependent descriptors (e.g. control)
   const refs = [];
   const bulkAction = { value: null };
   const legacyRenameAction = { value: null }; // 'rename_all' | 'skip_all' | null
   const config = await loadConfig();
 
-  for (const [descriptor, { dir, records }] of groups.entries()) {
+  const sortedGroups = [...groups.entries()].sort(([a], [b]) => {
+    if (a === 'descriptor_definition') return -1;
+    if (b === 'descriptor_definition') return 1;
+    return 0;
+  });
+
+  for (const [descriptor, { dir, records }] of sortedGroups) {
     const { filenameCol, companionRefs } = descriptorPrefs.get(descriptor);
     const useRootDoc = (descriptor === 'documentation' && docPlacement === 'root');
     const mdColInfo = useRootDoc ? companionRefs.find(r => r.extensionCol === 'md') : null;
@@ -2593,14 +2772,15 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
       }
 
       // Resolve name collisions: second+ record with same name gets -1, -2, etc.
+      // Use case-insensitive key to prevent companion file collisions on case-insensitive filesystems.
       const uid = record.UID || 'untitled';
-      const nameKey = name;
+      const nameKey = name.toLowerCase();
       const nameCount = usedNames.get(nameKey) || 0;
       usedNames.set(nameKey, nameCount + 1);
       if (nameCount > 0) name = `${name}-${nameCount}`;
 
-      // Metadata: name.metadata~uid.json; companion files use natural name
-      const metaPath = join(dir, buildMetaFilename(name, uid));
+      // Metadata: name.metadata.json; companion files use natural name
+      const metaPath = join(dir, buildMetaFilename(name));
 
       // Legacy detection: rename old-format metadata files to new convention
       const legacyDotExtMetaPath = join(dir, `${name}.${uid}.metadata.json`);
@@ -2819,7 +2999,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
     const resolvedName = resolvedFilenames.get(record.UID);
     const effectiveMetaPath = resolvedName
-      ? join(scanDir, buildMetaFilename(resolvedName, String(record.UID || record._id || 'untitled')))
+      ? join(scanDir, buildMetaFilename(resolvedName))
       : scanMetaPath;
     if (!(await fileExists(effectiveMetaPath))) {
       const staleMeta = { _entity: 'media', _foreignApp: true };
@@ -2881,7 +3061,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     // Use collision-resolved filename for metadata path when available (e.g. "_media" suffix)
     const resolvedName = resolvedFilenames.get(record.UID);
     const effectiveMetaPath = resolvedName
-      ? join(scanDir, buildMetaFilename(resolvedName, String(record.UID || record._id || 'untitled')))
+      ? join(scanDir, buildMetaFilename(resolvedName))
       : scanMetaPath;
     const scanExists = await fileExists(effectiveMetaPath);
 
@@ -2971,12 +3151,11 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     if (!dir) dir = BINS_DIR;
     await mkdir(dir, { recursive: true });
 
-    // Companion: natural name, no UID (use collision-resolved override if available)
-    const uid = String(record.UID || record._id || 'untitled');
+    // Companion: natural name (use collision-resolved override if available)
     const finalFilename = resolvedFilenames.get(record.UID) || sanitizeFilename(filename);
     const filePath = join(dir, finalFilename);
-    // Metadata: use collision-resolved filename as base (e.g. "env_media.js" → "env_media.js.metadata~uid.json")
-    const metaPath = join(dir, buildMetaFilename(finalFilename, uid));
+    // Metadata: use collision-resolved filename as base (e.g. "env_media.js" → "env_media.js.metadata.json")
+    const metaPath = join(dir, buildMetaFilename(finalFilename));
     // usedNames retained for tracking
     const fileKey = `${dir}/${name}.${ext}`;
     usedNames.set(fileKey, (usedNames.get(fileKey) || 0) + 1);
@@ -3248,7 +3427,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
       probeDir = probeDir.replace(/^\/+|\/+$/g, '') || BINS_DIR;
       if (extname(probeDir)) probeDir = probeDir.substring(0, probeDir.lastIndexOf('/')) || BINS_DIR;
 
-      const probeMeta = join(probeDir, buildMetaFilename(sanitized, uid));
+      const probeMeta = join(probeDir, buildMetaFilename(sanitized));
       const raw = await readFile(probeMeta, 'utf8');
       const localMeta = JSON.parse(raw);
       // Extract extension from Content @reference (e.g. "@Name~uid.html")
@@ -3339,8 +3518,8 @@ async function processRecord(entityName, record, structure, options, usedNames,
   const uid = String(record.UID || record._id || 'untitled');
   // Companion: natural name, no UID (use collision-resolved override if available)
   const fileName = filenameOverride || sanitizeFilename(buildContentFileName(record, uid));
-  // Metadata: name.metadata~uid.json
-  // usedNames retained for non-UID edge case tracking
+  // Metadata: filename.metadata.json (includes extension to avoid collisions between records
+  // with the same Name but different Extension, e.g. codeTest.js vs codeTest.css)
   const nameKey = `${dir}/${name}`;
   usedNames.set(nameKey, (usedNames.get(nameKey) || 0) + 1);
 
@@ -3352,7 +3531,20 @@ async function processRecord(entityName, record, structure, options, usedNames,
   );
 
   const filePath = join(dir, fileName);
-  const metaPath = join(dir, buildMetaFilename(name, uid));
+  const metaPath = join(dir, buildMetaFilename(fileName));
+
+  // Legacy migration: rename old name.metadata.json → new filename.metadata.json
+  // (repos cloned before this fix used the base name without extension as the metadata stem)
+  const legacyMetaPath = join(dir, buildMetaFilename(name));
+  if (legacyMetaPath !== metaPath && !await fileExists(metaPath) && await fileExists(legacyMetaPath)) {
+    try {
+      const legacyMeta = JSON.parse(await readFile(legacyMetaPath, 'utf8'));
+      if (legacyMeta.UID === uid) {
+        const { rename: fsRename } = await import('fs/promises');
+        await fsRename(legacyMetaPath, metaPath);
+      }
+    } catch { /* non-critical */ }
+  }
 
   // Rename legacy ~UID companion files to natural names if needed
   if (await fileExists(metaPath)) {
@@ -4081,22 +4273,32 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
     // Build root output filename (natural name, no UID in stem)
     const rootBasename = buildOutputFilename('output', output, filenameCols.output);
     const rootUid = output.UID || '';
-    let rootMetaPath = join(binDir, buildMetaFilename(rootBasename, rootUid));
+
+    // Resolve metadata path with collision detection (content records have priority over output).
+    // If name.metadata.json is owned by a different UID (e.g. a content record), use -1, -2, etc.
+    let rootMetaPath = await resolveMetaCollision(binDir, rootBasename, rootUid);
 
     // Legacy fallback: rename old-format metadata to new convention
     const legacyTildeOutputMeta = join(binDir, `${rootBasename}~${rootUid}.metadata.json`);
     const legacyJsonPath = join(binDir, `${rootBasename}.json`);
-    const legacyOutputMeta = join(binDir, `${rootBasename}.metadata.json`);
     if (!await fileExists(rootMetaPath)) {
       if (await fileExists(legacyTildeOutputMeta)) {
         await rename(legacyTildeOutputMeta, rootMetaPath);
         log.dim(`  Renamed ${basename(legacyTildeOutputMeta)} → ${basename(rootMetaPath)}`);
-      } else if (await fileExists(legacyOutputMeta)) {
-        await rename(legacyOutputMeta, rootMetaPath);
-        log.dim(`  Renamed ${basename(legacyOutputMeta)} → ${basename(rootMetaPath)}`);
       } else if (await fileExists(legacyJsonPath)) {
-        await rename(legacyJsonPath, rootMetaPath);
-        log.dim(`  Renamed ${rootBasename}.json → ${basename(rootMetaPath)}`);
+        // Only rename if the .json file actually looks like output metadata JSON.
+        // Content companions can share the same {name}.json filename pattern —
+        // renaming those would corrupt the content record's companion file.
+        let isOutputMeta = false;
+        try {
+          const legacyContent = await readFile(legacyJsonPath, 'utf8');
+          const legacyParsed = JSON.parse(legacyContent);
+          isOutputMeta = legacyParsed && (legacyParsed._entity === 'output' || legacyParsed.OutputID != null);
+        } catch { /* not valid JSON — definitely a content companion, skip */ }
+        if (isOutputMeta) {
+          await rename(legacyJsonPath, rootMetaPath);
+          log.dim(`  Renamed ${rootBasename}.json → ${basename(rootMetaPath)}`);
+        }
       }
     }
 
@@ -4206,28 +4408,34 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
 /**
  * Write root content files (manifest.json, CLAUDE.md, README.md, etc.) to the project root.
  *
- * For each filename in rootContentFiles:
- *   - If a matching content record exists in contentRefs: relocate the companion from
- *     lib/bins/app/<filename> to the project root, delete the bins/app copy, and rewrite
- *     the metadata to use Content: "@/<filename>" (root-relative). This fixes the duplicate
- *     bug where processRecord always writes companions next to the metadata file.
- *   - If no server record: generate a fallback stub at the project root.
+ * Two passes:
+ *   1. For each filename in rootContentFiles config: search contentRefs for a matching record,
+ *      relocate its companion to the project root, and rewrite the metadata to use
+ *      Content: "@/<filename>" (root-relative). Fall back to a stub if no server record.
+ *   2. Promote any remaining content records with BinID=null whose companion filename is also
+ *      in rootContentFiles (catches records not matched by pass 1's name/content/path heuristics).
  */
 async function writeRootContentFiles(appJson, contentRefs) {
   const rootFiles = await loadRootContentFiles();
-  if (!rootFiles.length) return;
+  const handledUids = new Set();
 
   for (const filename of rootFiles) {
-    const handled = await _writeRootFile(filename, appJson, contentRefs);
-    if (!handled) {
+    const handledUid = await _writeRootFile(filename, appJson, contentRefs);
+    if (handledUid) {
+      handledUids.add(handledUid);
+    } else {
       await _generateRootFileStub(filename, appJson);
     }
   }
+
+  // Promote any content records with no BinID that weren't already handled above,
+  // but only if the companion filename appears in rootContentFiles.
+  await _promoteNoBinContentToRoot(contentRefs, handledUids, rootFiles);
 }
 
 /**
  * Find the content record for a root file and relocate its companion to the project root.
- * Returns true if handled, false if no matching record was found.
+ * Returns the record UID if handled, null if no matching record was found.
  */
 async function _writeRootFile(filename, appJson, contentRefs) {
   const filenameLower = filename.toLowerCase();
@@ -4283,10 +4491,69 @@ async function _writeRootFile(filename, appJson, contentRefs) {
       await writeFile(ref.metaPath, JSON.stringify(updated, null, 2) + '\n');
     } catch { /* non-critical */ }
 
-    return true;
+    return ref.uid;
   }
 
-  return false; // No server record found
+  return null; // No server record found
+}
+
+/**
+ * Promote content records with no BinID to the project root.
+ * Only promotes records whose companion filename appears in rootContentFiles —
+ * records not in that list stay in their lib/bins/ placement.
+ * Skips records already handled by _writeRootFile (tracked via handledUids).
+ * Companion filename is extracted from the Content @-reference in the metadata.
+ */
+async function _promoteNoBinContentToRoot(contentRefs, handledUids, rootFiles) {
+  const rootFilesLower = new Set((rootFiles || []).map(f => f.toLowerCase()));
+  for (const ref of contentRefs) {
+    if (handledUids.has(ref.uid)) continue;
+
+    let meta;
+    try { meta = JSON.parse(await readFile(ref.metaPath, 'utf8')); } catch { continue; }
+
+    // Only promote records with no BinID
+    if (meta.BinID != null) continue;
+
+    // Extract companion filename from Content @-reference
+    const metaContent = String(meta.Content || '');
+    const contentRef = metaContent.startsWith('@/') ? metaContent.slice(2)
+      : metaContent.startsWith('@') ? metaContent.slice(1)
+      : null;
+
+    // Skip if no companion reference, if it includes a path (not a root-level file),
+    // or if it's not listed in rootContentFiles.
+    if (!contentRef || contentRef.includes('/')) continue;
+    if (!rootFilesLower.has(contentRef.toLowerCase())) continue;
+
+    const filename = contentRef;
+    const metaDir = dirname(ref.metaPath);
+    const localCompanion = join(metaDir, filename);
+    let content;
+    try {
+      content = await readFile(localCompanion, 'utf8');
+    } catch {
+      try { content = await readFile(join(process.cwd(), filename), 'utf8'); } catch { /* nothing */ }
+    }
+
+    if (content !== undefined) {
+      await writeFile(join(process.cwd(), filename), content);
+      log.dim(`  ${filename} written to project root (BinID=null)`);
+
+      if (localCompanion !== join(process.cwd(), filename)) {
+        try { await unlink(localCompanion); } catch { /* already gone or at root */ }
+      }
+    } else {
+      log.warn(`  Could not find companion file for ${filename} (BinID=null record)`);
+    }
+
+    // Rewrite metadata: root-relative Content reference
+    try {
+      const updated = { ...meta, Content: `@/${filename}` };
+      if (!updated._companionReferenceColumns) updated._companionReferenceColumns = ['Content'];
+      await writeFile(ref.metaPath, JSON.stringify(updated, null, 2) + '\n');
+    } catch { /* non-critical */ }
+  }
 }
 
 /**
@@ -4307,14 +4574,76 @@ async function _generateRootFileStub(filename, appJson) {
   }
 
   if (filenameLower === 'claude.md') {
-    const stub = `# ${appName}\n\nAdd Claude Code instructions for this project here.\n`;
+    const cfg = await loadConfig();
+    const domain = cfg.domain || '';
+    const appShortName = appJson.ShortName || '';
+    const siteRecords = appJson.children?.site || [];
+    const siteLines = siteRecords.map(s => {
+      const url = `//${domain}/app/${appShortName}/${s.ShortName}`;
+      const label = s.Title || s.Name || s.ShortName;
+      return `- \`${url}\` — ${label} (add \`?dev=true\` to serve uncompiled JS; add \`&console=true\` for verbose debug logging)`;
+    });
+    const stub = [
+      `# ${appName}`,
+      ...(siteLines.length > 0 ? [``, `## App Sites`, ``, ...siteLines] : []),
+      ``,
+      `## DBO CLI`,
+      ``,
+      `Always run \`dbo\` commands from the project root (the directory containing this CLAUDE.md file).`,
+      ``,
+      `## DBO API Submissions`,
+      ``,
+      `- To create new records, use the REST API (\`/api/input/submit\`) directly — the CLI has no \`add\` command.`,
+      `- This project may require a ticket ID for all submissions when the RepositoryIntegrationID column in the baseline JSON is set. Read it from \`.app/ticketing.local.json\` and include \`_OverrideTicketID={ticket_id}\` as a query parameter on every \`/api/input/submit\` call.`,
+      `- Cookie file for auth: \`.app/cookies.txt\``,
+      `- If the project's baseline JSON (\`.app/baseline.json\`) has a \`ModifyKey\` field, the app is not updatable and should not be edited. If you must, the user must be supplying that key as _modifyKey in the submission query parameters to update existing records.`,
+      `- Domain: read from \`.app/config.json\` (\`domain\` field)`,
+      ``,
+      `## Documentation`,
+      ``,
+      `Project docs may live in any of these locations:`,
+      ``,
+      `- \`CLAUDE.md\` _(this file)_`,
+      `- \`README.md\``,
+      `- \`docs/\``,
+      `- \`lib/bins/docs/\``,
+      `- \`lib/extension/Documentation/\``,
+      ``,
+      `For dependency apps, look under \`app_dependencies/<app_short_name>/\` using the same structure:`,
+      ``,
+      `- \`app_dependencies/<app_short_name>/CLAUDE.md\``,
+      `- \`app_dependencies/<app_short_name>/README.md\``,
+      `- \`app_dependencies/<app_short_name>/docs/\``,
+      `- \`app_dependencies/<app_short_name>/lib/bins/docs/\``,
+      `- \`app_dependencies/<app_short_name>/lib/extension/Documentation/\``,
+      ``,
+      `### DBO.io Framework API Reference`,
+      ``,
+      `For the DBO.io REST API (input/submit, output, content, etc.), check in priority order:`,
+      ``,
+      `1. \`app_dependencies/_system/lib/bins/docs/\` — authoritative source`,
+      `2. \`plugins/claude/dbo/skills/white-paper/references/\` — fallback reference`,
+      ``,
+    ].join('\n');
     await writeFile(rootPath, stub);
     log.dim(`  CLAUDE.md generated at project root (stub)`);
     return;
   }
 
   if (filenameLower === 'readme.md') {
+    const cfg = await loadConfig();
+    const domain = cfg.domain || '';
+    const appShortName = appJson.ShortName || '';
+    const siteRecords = appJson.children?.site || [];
     const parts = [`# ${appName}`];
+    if (siteRecords.length > 0) {
+      parts.push('');
+      for (const s of siteRecords) {
+        const url = `//${domain}/app/${appShortName}/${s.ShortName}`;
+        const label = s.Title || s.Name || s.ShortName;
+        parts.push(`- [${label}](${url})`);
+      }
+    }
     if (description) parts.push('', description);
     parts.push('');
     await writeFile(rootPath, parts.join('\n'));
@@ -4322,6 +4651,32 @@ async function _generateRootFileStub(filename, appJson) {
     return;
   }
 
+  if (filenameLower === 'package.json') {
+    const shortName = (appJson.ShortName || appName || 'app').toLowerCase().replace(/\s+/g, '-');
+    const stub = JSON.stringify({
+      name: shortName,
+      version: '1.0.0',
+      description: description || '',
+      private: true,
+    }, null, 2) + '\n';
+    await writeFile(rootPath, stub);
+    log.dim(`  package.json generated at project root (stub)`);
+    return;
+  }
+
+  if (filenameLower === '.dboignore') {
+    await writeFile(rootPath, getDboignoreDefaultContent());
+    log.dim(`  .dboignore generated at project root (stub)`);
+    return;
+  }
+
+  if (filenameLower === '.gitignore') {
+    const lines = DEFAULT_GITIGNORE_ENTRIES.map(e => e).join('\n') + '\n';
+    await writeFile(rootPath, lines);
+    log.dim(`  .gitignore generated at project root (stub)`);
+    return;
+  }
+
   // Unknown file type — no stub generated
 }