@dboio/cli 0.19.7 → 0.20.0

package/src/commands/clone.js

@@ -3,13 +3,13 @@ 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';
@@ -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,10 +383,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 +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 };
 }
 
@@ -1197,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
@@ -1222,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)
@@ -1415,7 +1458,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);
   }
 
@@ -1978,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`);
@@ -2217,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');
@@ -2284,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) {
@@ -2469,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)`);
@@ -2478,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',
@@ -2520,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
@@ -2568,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;
@@ -2593,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`);
@@ -2819,7 +2870,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 +2932,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 +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);
@@ -3248,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")
@@ -3339,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);
 
@@ -3352,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)) {
@@ -4081,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)}`);
+        }
       }
     }
 
@@ -4206,28 +4265,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 +4348,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,7 +4431,47 @@ async function _generateRootFileStub(filename, appJson) {
   }
 
   if (filenameLower === 'claude.md') {
-    const stub = `# ${appName}\n\nAdd Claude Code instructions for this project here.\n`;
+    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;
@@ -4322,6 +4486,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
 }
 

package/src/commands/init.js

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import { mkdir, writeFile, access } from 'fs/promises';
 import { join } from 'path';
-import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore, saveTransactionKeyPreset, saveTicketSuggestionOutput } from '../lib/config.js';
+import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore, DEFAULT_GITIGNORE_ENTRIES, saveTransactionKeyPreset, saveTicketSuggestionOutput } from '../lib/config.js';
 import { installOrUpdateClaudeCommands } from './install.js';
 import { scaffoldProjectDirs, logScaffoldResult } from '../lib/scaffold.js';
 import { createDboignore } from '../lib/ignore.js';
@@ -108,7 +108,7 @@ export const initCommand = new Command('init')
       }
 
       // Ensure sensitive files are gitignored
-      await ensureGitignore(['.app/credentials.json', '.app/cookies.txt', '.app/ticketing.local.json', '.app/scripts.local.json', '.app/errors.log', 'trash/', 'Icon\\r', 'app_dependencies/']);
+      await ensureGitignore(DEFAULT_GITIGNORE_ENTRIES);
 
       const createdIgnore = await createDboignore();
       if (createdIgnore) log.dim('  Created .dboignore');

package/src/commands/input.js

@@ -15,7 +15,7 @@ export const inputCommand = new Command('input')
   .description('Submit CRUD operations to DBO.io (add, edit, delete records)')
   .requiredOption('-d, --data <expr>', 'DBO input expression (repeatable)', collect, [])
   .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('-C, --confirm [value]', 'Commit changes: true (default) or false for validation only', 'true')
   .option('--ticket <id>', 'Override ticket ID (_OverrideTicketID)')
   .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--row-key <type>', 'Row key type (RowUID or RowID) — no-op for -d passthrough, available for consistency')
@@ -32,7 +32,7 @@ export const inputCommand = new Command('input')
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
       const extraParams = {};
-      extraParams['_confirm'] = options.confirm;
+      extraParams['_confirm'] = String(options.confirm);
       if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
       if (options.login) extraParams['_login'] = 'true';
       if (options.transactional) extraParams['_transactional'] = 'true';

package/src/commands/login.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { loadConfig, initConfig, saveUserInfo, saveUserProfile, ensureGitignore } from '../lib/config.js';
+import { loadConfig, initConfig, saveUserInfo, saveUserProfile, ensureGitignore, DEFAULT_GITIGNORE_ENTRIES } from '../lib/config.js';
 import { DboClient } from '../lib/client.js';
 import { log } from '../lib/logger.js';
 
@@ -49,7 +49,7 @@ export async function performLogin(domain, knownUsername) {
   }
 
   log.success(`Authenticated as ${username} on ${await client.getDomain()}`);
-  await ensureGitignore(['.app/credentials.json', '.app/cookies.txt', '.app/ticketing.local.json']);
+  await ensureGitignore(DEFAULT_GITIGNORE_ENTRIES);
 
   // Fetch and store user info (non-critical)
   try {
@@ -143,7 +143,7 @@ export const loginCommand = new Command('login')
         log.success(`Authenticated as ${username} on ${await client.getDomain()}`);
 
         // Ensure sensitive files are gitignored
-        await ensureGitignore(['.app/credentials.json', '.app/cookies.txt', '.app/ticketing.local.json']);
+        await ensureGitignore(DEFAULT_GITIGNORE_ENTRIES);
 
         // Fetch current user info to store ID for future submissions
         try {