@dboio/cli 0.19.4 → 0.20.0

package/src/commands/clone.js

@@ -1,15 +1,15 @@
 import { Command } from 'commander';
-import { readFile, writeFile, appendFile, mkdir, access, readdir, rename, stat, utimes } from 'fs/promises';
+import { readFile, writeFile, appendFile, mkdir, access, readdir, rename, stat, utimes, unlink } from 'fs/promises';
 import { join, basename, extname, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement } from '../lib/config.js';
+import { 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';
@@ -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) {
@@ -322,8 +353,8 @@ 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: name.metadata.json
+  const metaPath = join(dir, buildMetaFilename(name));
 
   return { dir, filename, metaPath };
 }
@@ -352,14 +383,33 @@ 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 };
 }
 
+/**
+ * Classify a media record based on its FullPath relative to the app short name.
+ *
+ * Returns:
+ *   'app'     — /media/<appShortName>/app/... or no FullPath (assumed app media)
+ *   'user'    — /media/<appShortName>/user/...
+ *   'foreign' — /media/<other_app>/... (belongs to a different app entirely)
+ */
+function classifyMediaRecord(record, appShortName) {
+  const fp = record.FullPath;
+  if (!fp || !appShortName) return 'app';
+  const normalized = fp.startsWith('/') ? fp.slice(1) : fp;
+  // Must start with media/<appShortName>/
+  const appPrefix = `media/${appShortName.toLowerCase()}/`;
+  if (!normalized.toLowerCase().startsWith(appPrefix)) return 'foreign';
+  const rest = normalized.slice(appPrefix.length);
+  if (rest.toLowerCase().startsWith('user/')) return 'user';
+  return 'app';
+}
+
 /**
  * Extract path components for entity-dir records.
  * Simplified from processEntityDirEntries() for collision detection.
@@ -377,8 +427,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 };
 }
 
@@ -1177,11 +1226,25 @@ 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) {
+    await updateConfigWithApp({ AppShortName: appJson.ShortName });
+  }
+
   // 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
@@ -1202,7 +1265,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)
@@ -1393,9 +1456,10 @@ export async function performClone(source, options = {}) {
     );
   }
 
-  // Step 5a: Write manifest.json to project root (skip for dependency checkouts)
-  if ((!entityFilter || entityFilter.has('content')) && !isDependencyCheckout()) {
-    await writeManifestJson(appJson, contentRefs);
+  // 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')) {
+    await writeRootContentFiles(appJson, contentRefs);
   }
 
   // Step 5b: Process media → download binary files + metadata (skip rejected records)
@@ -1957,14 +2021,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`);
@@ -2196,7 +2261,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');
@@ -2263,9 +2328,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) {
@@ -2448,8 +2514,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)`);
@@ -2457,7 +2521,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',
@@ -2499,7 +2563,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
@@ -2547,12 +2611,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;
@@ -2572,14 +2643,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`);
@@ -2775,22 +2847,92 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
 async function processMediaEntries(mediaRecords, structure, options, config, appShortName, serverTz, skipUIDs = new Set(), resolvedFilenames = new Map()) {
   if (!mediaRecords || mediaRecords.length === 0) return [];
 
+  // ── Step 0: Classify records by path scope ──────────────────────────────
+  // foreign = /media/<other_app>/... (not this app — never download)
+  // user    = /media/<appShortName>/user/... (opt-in via UserMedia config)
+  // app     = /media/<appShortName>/app/... or no FullPath (always download)
+  const foreignRecords = [];
+  const userRecords = [];
+  const appRecords = [];
+
+  for (const record of mediaRecords) {
+    if (skipUIDs.has(record.UID)) continue;
+    const cls = classifyMediaRecord(record, appShortName);
+    if (cls === 'foreign') foreignRecords.push(record);
+    else if (cls === 'user') userRecords.push(record);
+    else appRecords.push(record);
+  }
+
+  // Silently write stale metadata for foreign records so they are never
+  // re-prompted on future clones. No download is attempted.
+  const foreignRefs = [];
+  for (const record of foreignRecords) {
+    const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
+    const resolvedName = resolvedFilenames.get(record.UID);
+    const effectiveMetaPath = resolvedName
+      ? join(scanDir, buildMetaFilename(resolvedName))
+      : scanMetaPath;
+    if (!(await fileExists(effectiveMetaPath))) {
+      const staleMeta = { _entity: 'media', _foreignApp: true };
+      for (const [k, v] of Object.entries(record)) {
+        if (k !== 'children') staleMeta[k] = v;
+      }
+      try {
+        await mkdir(scanDir, { recursive: true });
+        await writeFile(effectiveMetaPath, JSON.stringify(staleMeta, null, 2) + '\n');
+        if (serverTz && (record._CreatedOn || record._LastUpdated)) {
+          await setFileTimestamps(effectiveMetaPath, record._CreatedOn, record._LastUpdated, serverTz);
+        }
+      } catch { /* non-critical */ }
+    }
+    foreignRefs.push({ uid: record.UID, metaPath: effectiveMetaPath });
+  }
+  if (foreignRecords.length > 0) {
+    log.dim(`  Skipped ${foreignRecords.length} foreign media file(s) (not in /media/${appShortName || '?'}/)`);
+  }
+
+  // ── User media: prompt once if preference is unset ───────────────────────
+  // config.UserMedia: true = include, false = skip, undefined = not yet asked
+  let includeUserMedia = config.UserMedia ?? null;
+  if (userRecords.length > 0 && includeUserMedia === null && !options.yes) {
+    const inquirer = (await import('inquirer')).default;
+    const exampleFile = userRecords[0].Filename || userRecords[0].Name || 'user file';
+    const { includeUser } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'includeUser',
+      message: `App has ${userRecords.length} user media file(s) (e.g. "${exampleFile}"). Download user media? (saves preference)`,
+      default: false,
+    }]);
+    includeUserMedia = includeUser;
+    await updateConfigUserMedia(includeUserMedia);
+  } else if (userRecords.length > 0 && options.yes && includeUserMedia === null) {
+    // Non-interactive: default to false, save preference
+    includeUserMedia = false;
+    await updateConfigUserMedia(false);
+  }
+
+  if (!includeUserMedia && userRecords.length > 0) {
+    log.dim(`  Skipped ${userRecords.length} user media file(s) (UserMedia=false)`);
+  }
+
+  // Active records = app media + user media (if opted in)
+  const activeRecords = includeUserMedia ? [...appRecords, ...userRecords] : appRecords;
+
   // Track stale records (404s) for cleanup prompt
   const staleRecords = [];
 
   // Pre-scan: determine which media files actually need downloading
   // (new files or files with newer server timestamps)
   const needsDownload = [];
-  const upToDateRefs = [];
+  const upToDateRefs = [...foreignRefs];
 
-  for (const record of mediaRecords) {
-    if (skipUIDs.has(record.UID)) continue;
+  for (const record of activeRecords) {
 
     const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
     // 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);
 
@@ -2815,7 +2957,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   }
 
   if (needsDownload.length === 0) {
-    log.dim(`  All ${mediaRecords.length} media file(s) up to date`);
+    log.dim(`  All ${activeRecords.length} media file(s) up to date`);
     return upToDateRefs;
   }
 
@@ -2828,7 +2970,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const { download } = await inquirer.prompt([{
       type: 'confirm',
       name: 'download',
-      message: `${needsDownload.length} media file(s) need to be downloaded (${mediaRecords.length - needsDownload.length} up to date). Attempt download now?`,
+      message: `${needsDownload.length} media file(s) need to be downloaded (${activeRecords.length - needsDownload.length} up to date). Attempt download now?`,
       default: true,
     }]);
     canDownload = download;
@@ -2857,9 +2999,9 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   let downloaded = 0;
   let failed = 0;
 
-  log.info(`Downloading ${mediaRecords.length} media file(s)...`);
+  log.info(`Downloading ${activeRecords.length} media file(s)...`);
 
-  for (const record of mediaRecords) {
+  for (const record of activeRecords) {
     const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
 
     if (skipUIDs.has(record.UID)) {
@@ -2880,12 +3022,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);
@@ -3157,7 +3298,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")
@@ -3248,8 +3389,7 @@ 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: name.metadata.json; usedNames retained for non-UID edge case tracking
   const nameKey = `${dir}/${name}`;
   usedNames.set(nameKey, (usedNames.get(nameKey) || 0) + 1);
 
@@ -3261,7 +3401,7 @@ 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(name));
 
   // Rename legacy ~UID companion files to natural names if needed
   if (await fileExists(metaPath)) {
@@ -3990,22 +4130,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)}`);
+        }
       }
     }
 
@@ -4113,53 +4263,267 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
 }
 
 /**
- * Write manifest.json to project root.
- * If a manifest content record was cloned from the server, use its Content value.
- * Otherwise, generate from appJson values (empty strings for missing fields).
+ * Write root content files (manifest.json, CLAUDE.md, README.md, etc.) to 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 writeManifestJson(appJson, contentRefs) {
-  // 1. Search contentRefs for a manifest content record
+async function writeRootContentFiles(appJson, contentRefs) {
+  const rootFiles = await loadRootContentFiles();
+  const handledUids = new Set();
+
+  for (const filename of rootFiles) {
+    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 the record UID if handled, null if no matching record was found.
+ */
+async function _writeRootFile(filename, appJson, contentRefs) {
+  const filenameLower = filename.toLowerCase();
+  const stemLower = filenameLower.includes('.') ? filenameLower.slice(0, filenameLower.lastIndexOf('.')) : filenameLower;
+  const extLower = filenameLower.includes('.') ? filenameLower.slice(filenameLower.lastIndexOf('.') + 1) : '';
+
   for (const ref of contentRefs) {
     let meta;
+    try { meta = JSON.parse(await readFile(ref.metaPath, 'utf8')); } catch { continue; }
+
+    // Match by Name+Extension, or by Content @reference, or by Path
+    const metaName = (meta.Name || '').toLowerCase();
+    const metaExt = (meta.Extension || '').toLowerCase();
+    const metaContent = String(meta.Content || '');
+    const metaPath2 = String(meta.Path || '');
+    const contentRef = metaContent.startsWith('@/') ? metaContent.slice(2)
+      : metaContent.startsWith('@') ? metaContent.slice(1)
+      : null;
+
+    const matchByName = metaName.startsWith(stemLower) && metaExt === extLower;
+    const matchByContent = contentRef && contentRef.toLowerCase() === filenameLower;
+    const matchByPath = metaPath2.replace(/^\//, '').toLowerCase() === filenameLower;
+
+    if (!matchByName && !matchByContent && !matchByPath) continue;
+
+    // Found a matching record — read companion content from bins/app dir
+    const metaDir = dirname(ref.metaPath);
+    const localCompanion = join(metaDir, filename);
+    let content;
     try {
-      meta = JSON.parse(await readFile(ref.metaPath, 'utf8'));
-    } catch { continue; }
-
-    const name = (meta.Name || '').toLowerCase();
-    const ext = (meta.Extension || '').toLowerCase();
-    if (name.startsWith('manifest') && ext === 'json') {
-      // Found manifest — read content file and write to project root
-      const contentRef = meta.Content;
-      if (contentRef && String(contentRef).startsWith('@')) {
-        const refFile = String(contentRef).substring(1);
-        // Try root-relative first, then sibling of metadata, then project root fallback
-        const candidates = refFile.startsWith('/')
-          ? [join(process.cwd(), refFile)]
-          : [join(dirname(ref.metaPath), refFile), join(process.cwd(), refFile)];
-        let content;
-        for (const candidate of candidates) {
-          try {
-            content = await readFile(candidate, 'utf8');
-            break;
-          } catch { /* try next */ }
-        }
-        if (content !== undefined) {
-          await writeFile('manifest.json', content);
-          log.dim('  manifest.json written to project root (from server content)');
-        } else {
-          log.warn(`  Could not find manifest.json companion file`);
-        }
+      content = await readFile(localCompanion, 'utf8');
+    } catch {
+      // Companion may already be at root (re-clone scenario) or never written (no Content on server)
+      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 (from server content)`);
+
+      // Delete stale companion in bins/app if it exists there
+      if (localCompanion !== join(process.cwd(), filename)) {
+        try { await unlink(localCompanion); } catch { /* already gone or at root */ }
       }
-      return;
+    } else {
+      log.warn(`  Could not find companion file for ${filename}`);
+    }
+
+    // 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 */ }
+
+    return ref.uid;
+  }
+
+  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 */ }
+  }
+}
+
+/**
+ * Generate a fallback stub for a root content file when the server has no record.
+ * Skips if the file already exists at the project root.
+ */
+async function _generateRootFileStub(filename, appJson) {
+  const rootPath = join(process.cwd(), filename);
+  try { await access(rootPath); return; } catch { /* doesn't exist — generate */ }
+
+  const appName = appJson.Name || appJson.ShortName || '';
+  const description = appJson.Description || '';
+  const filenameLower = filename.toLowerCase();
+
+  if (filenameLower === 'manifest.json') {
+    await _generateManifestFallback(appJson);
+    return;
+  }
+
+  if (filenameLower === 'claude.md') {
+    const stub = [
+      `# ${appName}`,
+      ``,
+      `## 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;
   }
 
-  // 2. No manifest content record — generate from appJson values
+  if (filenameLower === 'readme.md') {
+    const parts = [`# ${appName}`];
+    if (description) parts.push('', description);
+    parts.push('');
+    await writeFile(rootPath, parts.join('\n'));
+    log.dim(`  README.md generated at project root (stub)`);
+    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
+}
+
+/**
+ * Generate manifest.json at project root from appJson values.
+ * Preserves existing behaviour from the old writeManifestJson fallback.
+ */
+async function _generateManifestFallback(appJson) {
   const shortName = appJson.ShortName || '';
   const appName = appJson.Name || '';
   const description = appJson.Description || '';
 
-  // Find background_color from extension children (widget descriptor matching ShortName)
   let bgColor = '#ffffff';
   if (shortName) {
     const extensions = appJson.children?.extension || [];
@@ -4191,7 +4555,7 @@ async function writeManifestJson(appJson, contentRefs) {
     icons: [],
   };
 
-  await writeFile('manifest.json', JSON.stringify(manifest, null, 2) + '\n');
+  await writeFile(join(process.cwd(), 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
   log.dim('  manifest.json generated at project root (from app metadata)');
 }