@dboio/cli 0.19.7 → 0.20.0

package/src/commands/push.js

@@ -1,6 +1,6 @@
 import { Command } from 'commander';
-import { readFile, stat, writeFile, rename as fsRename, mkdir, access, utimes } from 'fs/promises';
-import { join, dirname, basename, extname, relative } from 'path';
+import { readFile, stat, writeFile, rename as fsRename, mkdir, access, utimes, readdir } from 'fs/promises';
+import { join, dirname, basename, extname, relative, sep } from 'path';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody, checkSubmitErrors, getSessionUserOverride } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
@@ -12,7 +12,7 @@ import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, cl
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { setFileTimestamps, parseServerDate } from '../lib/timestamps.js';
-import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
+import { stripUidFromFilename, renameToUidConvention, isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { findMetadataFiles, findFileInProject, findByUID } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { detectChangedColumns, findBaselineEntry, detectOutputChanges, detectEntityChildrenChanges, getAllUserColumns, isReference, resolveReferencePath, detectBinChanges, synthesizeBinMetadata } from '../lib/delta.js';
@@ -480,7 +480,7 @@ async function ensureRootContentFiles() {
   const ig = await loadIgnore();
   const allMeta = await findMetadataFiles(process.cwd(), ig);
 
-  // Build a set of already-tracked filenames from existing metadata.
+  // Build a set of already-tracked filenames from existing metadata (lowercase for case-insensitive match).
   // Also strip stale fields (e.g. Descriptor) from content-entity root file metadata.
   const tracked = new Set();
   for (const metaPath of allMeta) {
@@ -493,8 +493,8 @@ async function ensureRootContentFiles() {
       const refName = content.startsWith('@/') ? content.slice(2)
         : content.startsWith('@') ? content.slice(1)
         : null;
-      if (refName) tracked.add(refName);
-      if (path) tracked.add(path.replace(/^\//, ''));
+      if (refName) tracked.add(refName.toLowerCase());
+      if (path) tracked.add(path.replace(/^\//, '').toLowerCase());
 
       // Clean up stale Descriptor field: content entities never have Descriptor.
       // This fixes metadata written by an earlier buggy version of the tool.
@@ -515,10 +515,11 @@ async function ensureRootContentFiles() {
   for (const filename of rootFiles) {
     // Skip if file doesn't exist at project root
     try { await access(join(process.cwd(), filename)); } catch { continue; }
-    // Skip if already tracked by existing metadata
-    if (tracked.has(filename)) continue;
+    // Skip if already tracked by existing metadata (case-insensitive)
+    if (tracked.has(filename.toLowerCase())) continue;
 
-    const tmpl = ROOT_FILE_TEMPLATES[filename] || {
+    const tmplKey = Object.keys(ROOT_FILE_TEMPLATES).find(k => k.toLowerCase() === filename.toLowerCase());
+    const tmpl = (tmplKey ? ROOT_FILE_TEMPLATES[tmplKey] : null) || {
       _entity: 'content',
       _companionReferenceColumns: ['Content'],
       Extension: (filename.includes('.') ? filename.split('.').pop().toUpperCase() : 'TXT'),
@@ -544,6 +545,62 @@ async function ensureRootContentFiles() {
   }
 }
 
+/**
+ * Collect all non-metadata file absolute paths from a directory (recursive).
+ */
+async function collectCompanionFiles(dirPath, ig) {
+  const results = [];
+  let entries;
+  try { entries = await readdir(dirPath, { withFileTypes: true }); } catch { return results; }
+  for (const entry of entries) {
+    const fullPath = join(process.cwd(), dirPath, entry.name);
+    if (entry.isDirectory()) {
+      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+      if (!ig.ignores(relPath + '/') && !ig.ignores(relPath)) {
+        results.push(...await collectCompanionFiles(join(dirPath, entry.name), ig));
+      }
+    } else if (!isMetadataFile(entry.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Find metadata files project-wide that reference companion files in a given set via @reference.
+ * Used when pushing a directory like docs/ whose metadata lives elsewhere (e.g. lib/extension/Documentation/).
+ */
+async function findCrossDirectoryMetadata(dirPath, ig) {
+  const companionFiles = await collectCompanionFiles(dirPath, ig);
+  if (companionFiles.length === 0) return [];
+
+  const companionSet = new Set(companionFiles);
+  const appDepsPrefix = join(process.cwd(), 'app_dependencies') + sep;
+  const allMetaFiles = (await findMetadataFiles(process.cwd(), ig))
+    .filter(p => !p.startsWith(appDepsPrefix));
+  const found = [];
+
+  for (const metaPath of allMetaFiles) {
+    try {
+      const candidateMeta = JSON.parse(await readFile(metaPath, 'utf8'));
+      const metaDir = dirname(metaPath);
+      const cols = [...(candidateMeta._companionReferenceColumns || candidateMeta._contentColumns || [])];
+      if (candidateMeta._mediaFile) cols.push('_mediaFile');
+      for (const col of cols) {
+        const ref = candidateMeta[col];
+        if (!ref || !String(ref).startsWith('@')) continue;
+        const resolved = resolveAtReference(String(ref).substring(1), metaDir);
+        if (companionSet.has(resolved)) {
+          found.push(metaPath);
+          break;
+        }
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  return found;
+}
+
 /**
  * Push all records found in a directory (recursive)
  */
@@ -559,6 +616,14 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   const ig = await loadIgnore();
   const metaFiles = await findMetadataFiles(dirPath, ig);
 
+  // Cross-directory metadata lookup: if the target dir has no metadata files of its own
+  // (e.g. docs/ only contains .md companions, with metadata in lib/extension/Documentation/),
+  // find metadata files project-wide that reference those companions via @reference.
+  if (metaFiles.length === 0) {
+    const crossMetas = await findCrossDirectoryMetadata(dirPath, ig);
+    metaFiles.push(...crossMetas);
+  }
+
   // ── Load scripts config early (before delta detection) ──────────────
   // Build hooks must run BEFORE delta detection so compiled output files
   // (SASS → CSS, Rollup → JS, etc.) are on disk when changes are detected.
@@ -1440,24 +1505,19 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   // Clean up per-record ticket on success
   await clearRecordTicket(uid || id);
 
-  // Post-UID rename: if the record lacked a UID and the server returned one
+  // Post-insert UID write: if the record lacked a UID and the server returned one
   try {
     const editResults2 = result.payload?.Results?.Edit || result.data?.Payload?.Results?.Edit || [];
     const addResults2 = result.payload?.Results?.Add || result.data?.Payload?.Results?.Add || [];
     const allResults = [...editResults2, ...addResults2];
     if (allResults.length > 0 && !meta.UID) {
       const serverUID = allResults[0].UID;
-      if (serverUID && !hasUidInFilename(basename(metaPath), serverUID)) {
+      if (serverUID) {
         const config2 = await loadConfig();
-        const renameResult = await renameToUidConvention(meta, metaPath, serverUID, allResults[0]._LastUpdated, config2.ServerTimezone);
-        if (renameResult.newMetaPath !== metaPath) {
-          log.success(`  Renamed to ~${serverUID} convention`);
-          // Update metaPath reference for subsequent timestamp operations
-          // (metaPath is const, but timestamp update below re-reads from meta)
-        }
+        await renameToUidConvention(meta, metaPath, serverUID, allResults[0]._LastUpdated, config2.ServerTimezone);
       }
     }
-  } catch { /* non-critical rename */ }
+  } catch { /* non-critical */ }
 
   // Update file timestamps from server response
   try {

package/src/commands/status.js

@@ -59,16 +59,24 @@ export const statusCommand = new Command('status')
         log.plain('');
         log.info('Claude Code Plugins:');
         for (const [name, scope] of Object.entries(scopes)) {
-          const resolvedScope = scope || 'project';
-          const fileName = `${name}.md`;
-          let location;
-          if (resolvedScope === 'global') {
-            location = join(homedir(), '.claude', 'commands', fileName);
+          let resolvedScope, location;
+          if (Array.isArray(scope)) {
+            // Registry format: [{ scope: 'user'|'project', installPath, ... }]
+            const entry = scope[0];
+            resolvedScope = entry.scope === 'user' ? 'global' : (entry.scope || 'project');
+            location = entry.installPath;
           } else {
-            location = join(process.cwd(), '.claude', 'commands', fileName);
+            // Legacy format: scope is a plain string
+            resolvedScope = scope || 'project';
+            const fileName = `${name}.md`;
+            location = resolvedScope === 'global'
+              ? join(homedir(), '.claude', 'commands', fileName)
+              : join(process.cwd(), '.claude', 'commands', fileName);
           }
           let installed = false;
-          try { await access(location); installed = true; } catch {}
+          if (location) {
+            try { await access(location); installed = true; } catch {}
+          }
           const icon = installed ? '\u2713' : '\u2717';
           const scopeLabel = resolvedScope === 'global' ? 'global' : 'project';
           log.label(`  ${name}`, `${icon} ${scopeLabel} (${installed ? location : 'not found'})`);

package/src/lib/config.js

@@ -527,7 +527,7 @@ export async function removeAppJsonReference(metaPath) {
 // ─── config.local.json (global ~/.dbo/settings.json) ────────────────────
 
 function configLocalPath() {
-  return join(homedir(), '.dbo', CONFIG_LOCAL_FILE);
+  return process.env.DBO_SETTINGS_PATH || join(homedir(), '.dbo', CONFIG_LOCAL_FILE);
 }
 
 async function ensureGlobalDboDir() {
@@ -817,8 +817,58 @@ export async function removeFromGitignore(pattern) {
   log.dim(`  Removed ${pattern} from .gitignore`);
 }
 
+/** Canonical set of gitignore entries for DBO CLI projects. */
+export const DEFAULT_GITIGNORE_ENTRIES = [
+  '*local.',
+  '.DS_Store',
+  '*.DS_Store',
+  '*/.DS_Store',
+  '.idea*',
+  '.vscode*',
+  '*/node_modules',
+  'config.codekit3',
+  '/node_modules/',
+  'cookies.txt',
+  '*app.compiled.js',
+  '*.min.css',
+  '*.min.js',
+  '.profile',
+  '.secret',
+  '.password',
+  '.username',
+  '.cookies',
+  '.domain',
+  '.OverrideTicketID',
+  'media/*',
+  '',
+  '# DBO CLI (sensitive files)',
+  '.app/credentials.json',
+  '.app/cookies.txt',
+  '.app/ticketing.local.json',
+  'trash/',
+  '.app.json',
+  '',
+  '.app/scripts.local.json',
+  '.app/errors.log',
+  '',
+  '# DBO CLI (machine-generated baselines — regenerated by dbo pull/clone)',
+  '.app/operator.json',
+  '.app/operator.metadata.json',
+  '.app/synchronize.json',
+  'app_dependencies/',
+  '',
+  '# DBO CLI Claude Code commands (managed by dbo-cli)',
+  '.claude/plugins/dbo/',
+  '',
+  '# DBO CLI Claude Code commands (managed by dbo-cli)',
+  '.claude/plugins/track/',
+];
+
 /**
- * Ensure patterns are in .gitignore. Creates .gitignore if it doesn't exist.
+ * Ensure entries are in .gitignore. Creates .gitignore if it doesn't exist.
+ * Accepts an array that may include comment lines and blank separators;
+ * only entries not already present in the file are appended, preserving
+ * the section structure (comments, blank lines) of the input list.
  */
 export async function ensureGitignore(patterns) {
   const gitignorePath = join(process.cwd(), '.gitignore');
@@ -827,18 +877,48 @@ export async function ensureGitignore(patterns) {
     content = await readFile(gitignorePath, 'utf8');
   } catch { /* no .gitignore yet */ }
 
-  const toAdd = patterns.filter(p => !content.includes(p));
-  if (toAdd.length === 0) return;
+  const isMissing = entry => entry.trim() !== '' && !content.includes(entry);
+  if (!patterns.some(isMissing)) return;
+
+  // Build the block to append: include missing entries with their surrounding
+  // structure (comments, blank separators), omitting blanks that end up adjacent
+  // to already-present entries.
+  const outputLines = [];
+  let prevWasContent = false;
+
+  for (const entry of patterns) {
+    if (entry.trim() === '') {
+      if (prevWasContent) outputLines.push('');
+      prevWasContent = false;
+      continue;
+    }
+    if (isMissing(entry)) {
+      outputLines.push(entry);
+      prevWasContent = true;
+    } else {
+      // Entry already exists — remove any optimistically-added trailing blank.
+      if (!prevWasContent && outputLines.length > 0 && outputLines[outputLines.length - 1].trim() === '') {
+        outputLines.pop();
+      }
+      prevWasContent = false;
+    }
+  }
+
+  // Strip trailing blank lines.
+  while (outputLines.length > 0 && outputLines[outputLines.length - 1].trim() === '') {
+    outputLines.pop();
+  }
+
+  if (outputLines.length === 0) return;
 
   const isNew = content.length === 0;
   const needsNewline = !isNew && !content.endsWith('\n');
-  const hasHeader = content.includes('# DBO CLI');
-  const section = needsNewline ? '\n' : '';
-  const header = hasHeader ? '' : (isNew ? '# DBO CLI (sensitive files)\n' : '\n# DBO CLI (sensitive files)\n');
-  const addition = `${section}${header}${toAdd.join('\n')}\n`;
+  const prefix = needsNewline ? '\n\n' : (isNew ? '' : '\n');
+
+  await writeFile(gitignorePath, content + prefix + outputLines.join('\n') + '\n');
 
-  await writeFile(gitignorePath, content + addition);
-  for (const p of toAdd) log.dim(`  Added ${p} to .gitignore`);
+  const added = outputLines.filter(l => l.trim() !== '' && !l.startsWith('#'));
+  for (const p of added) log.dim(`  Added ${p} to .gitignore`);
 }
 
 // ─── Baseline (.app/<shortName>.json) ─────────────────────────────────────
@@ -1086,7 +1166,7 @@ export async function loadScriptsLocal() {
 
 // ─── Root Content Files ───────────────────────────────────────────────────────
 
-const ROOT_CONTENT_FILES_DEFAULTS = ['CLAUDE.md', 'README.md', 'manifest.json'];
+const ROOT_CONTENT_FILES_DEFAULTS = ['CLAUDE.md', 'README.md', 'manifest.json', 'package.json', '.dboignore', '.gitignore'];
 
 /**
  * Load rootContentFiles from .app/config.json.

package/src/lib/filenames.js

@@ -1,7 +1,7 @@
 /**
- * Filename convention helpers for the metadata~uid convention.
- * Metadata files: name.metadata~uid.json
- * Companion files: natural names, no UID embedded.
+ * Filename convention helpers for the metadata convention.
+ * Metadata files: name.metadata.json  (UID is stored inside the JSON, not in the filename)
+ * Companion files: natural names.
  */
 
 import { rename, unlink, writeFile, readFile, readdir } from 'fs/promises';
@@ -15,6 +15,8 @@ import { join, dirname, basename, extname } from 'path';
  * @param {string} uid   - Server-assigned UID
  * @param {string} [ext] - File extension WITHOUT leading dot (e.g. 'css', 'png', '')
  * @returns {string}     - e.g. "colors~abc123.css" or "abc123.css" or "colors~abc123"
+ * @deprecated Use buildMetaFilename() for metadata files. This function is retained
+ *             only for legacy detection/migration code.
  */
 export function buildUidFilename(name, uid, ext = '') {
   const base = (name === uid) ? uid : `${name}~${uid}`;
@@ -100,6 +102,7 @@ export function stripUidFromFilename(localName, uid) {
 
 /**
  * Check whether a filename already contains ~<uid>.
+ * @deprecated Only used by legacy migration code.
  */
 export function hasUidInFilename(filename, uid) {
   return typeof filename === 'string' && typeof uid === 'string'
@@ -114,25 +117,28 @@ export function hasUidInFilename(filename, uid) {
  * Returns { name, uid } or null.
  */
 export function detectLegacyDotUid(filename) {
-  const match = filename.match(/^(.+)\.([a-z0-9]{10,})\.metadata\.json$/);
+  const match = filename.match(/^(.+)\.([a-z0-9_]{10,})\.metadata\.json$/);
   return match ? { name: match[1], uid: match[2] } : null;
 }
 
 /**
- * Build the new-convention metadata filename.
- * Format: <naturalBase>.metadata~<uid>.json
+ * Build a metadata filename for a record.
+ * Format: <naturalBase>.metadata.json
+ * The UID is stored inside the JSON, not in the filename.
  *
- * For content records: naturalBase = "colors" → "colors.metadata~abc123.json"
- * For media records:   naturalBase = "logo.png" → "logo.png.metadata~abc123.json"
- * For output records:  naturalBase = "Sales" → "Sales.metadata~abc123.json"
+ * For content records:  naturalBase = "colors"    → "colors.metadata.json"
+ * For media records:    naturalBase = "logo.png"  → "logo.png.metadata.json"
+ * For output records:   naturalBase = "Sales"     → "Sales.metadata.json"
+ *
+ * Collision avoidance (when two records share a name) is handled by the caller
+ * via numbered suffixes: "colors-1.metadata.json", "colors-2.metadata.json", etc.
  *
  * @param {string} naturalBase - Name without any ~uid (may include media extension)
- * @param {string} uid         - Server-assigned UID
  * @returns {string}
  */
-export function buildMetaFilename(naturalBase, uid) {
+export function buildMetaFilename(naturalBase) {
   // Guard: strip any trailing .metadata suffix(es) and ~uid fragments from naturalBase
-  // to prevent double-metadata filenames (e.g., "app.metadata.metadata~app.json")
+  // to prevent double-metadata filenames (e.g., "app.metadata.metadata.json")
   let base = naturalBase;
   const metaParsed = parseMetaFilename(base + '.json');
   if (metaParsed) {
@@ -142,34 +148,43 @@ export function buildMetaFilename(naturalBase, uid) {
   while (base.endsWith('.metadata')) {
     base = base.substring(0, base.length - 9);
   }
-  return `${base}.metadata~${uid}.json`;
+  return `${base}.metadata.json`;
 }
 
 /**
  * Test whether a filename is a metadata file (new or legacy format).
  *
- * New format:    name.metadata~uid.json
- * Legacy format: name~uid.metadata.json  (also accepted during migration)
+ * New format:    name.metadata.json  (UID in JSON content, not filename)
+ * Legacy format: name.metadata~uid.json  (also accepted during migration)
  *
  * @param {string} filename
  * @returns {boolean}
  */
 export function isMetadataFile(filename) {
-  return /\.metadata~[a-z0-9]+\.json$/i.test(filename)   // new: name.metadata~uid.json
-    || filename.endsWith('.metadata.json')                 // legacy + pre-UID temp files
-    || /\.[a-z0-9]{10,}\.metadata\.json$/i.test(filename); // legacy dot-separated: name.uid.metadata.json
+  return filename.endsWith('.metadata.json')                 // new format + legacy pre-UID temp files
+    || /\.metadata~[a-z0-9_]+\.json$/i.test(filename)       // legacy tilde-uid suffix format
+    || /\.[a-z0-9]{10,}\.metadata\.json$/i.test(filename);  // legacy dot-separated: name.uid.metadata.json
 }
 
 /**
- * Parse a new-format metadata filename into its components.
- * Returns null for legacy-format filenames (use detectLegacyTildeMetadata for those).
+ * Parse a metadata filename into its components.
+ *
+ * New format:    name.metadata.json      → { naturalBase: "name" }
+ * Legacy format: name.metadata~uid.json  → { naturalBase: "name", uid: "uid" }
  *
- * @param {string} filename - e.g. "colors.metadata~abc123.json"
- * @returns {{ naturalBase: string, uid: string } | null}
+ * Returns null for non-metadata filenames.
+ *
+ * @param {string} filename
+ * @returns {{ naturalBase: string, uid?: string } | null}
  */
 export function parseMetaFilename(filename) {
-  const m = filename.match(/^(.+)\.metadata~([a-z0-9]+)\.json$/i);
-  return m ? { naturalBase: m[1], uid: m[2] } : null;
+  // Legacy format with uid in suffix (migration target for 008, source for 013)
+  const legacy = filename.match(/^(.+)\.metadata~([a-z0-9_]+)\.json$/i);
+  if (legacy) return { naturalBase: legacy[1], uid: legacy[2] };
+
+  // New format: name.metadata.json
+  const m = filename.match(/^(.+)\.metadata\.json$/i);
+  return m ? { naturalBase: m[1] } : null;
 }
 
 /**
@@ -181,11 +196,11 @@ export function parseMetaFilename(filename) {
  */
 export function detectLegacyTildeMetadata(filename) {
   // Case 1: name~uid.metadata.json (content/entity metadata)
-  const m1 = filename.match(/^(.+)~([a-z0-9]{10,})\.metadata\.json$/);
+  const m1 = filename.match(/^(.+)~([a-z0-9_]{10,})\.metadata\.json$/);
   if (m1) return { naturalBase: m1[1], uid: m1[2] };
 
   // Case 2: name~uid.ext.metadata.json (media metadata)
-  const m2 = filename.match(/^(.+)~([a-z0-9]{10,})\.([a-z0-9]+)\.metadata\.json$/);
+  const m2 = filename.match(/^(.+)~([a-z0-9_]{10,})\.([a-z0-9]+)\.metadata\.json$/);
   if (m2) return { naturalBase: `${m2[1]}.${m2[3]}`, uid: m2[2] };
 
   return null;
@@ -210,7 +225,7 @@ export async function findMetadataForCompanion(companionPath) {
   let entries;
   try { entries = await readdir(dir); } catch { return null; }
 
-  // 1. Fast path: match naturalBase of new-format metadata files
+  // 1. Fast path: match naturalBase of metadata files
   for (const entry of entries) {
     const parsed = parseMetaFilename(entry);
     if (parsed && (parsed.naturalBase === base || parsed.naturalBase === companionName)) {
@@ -218,7 +233,7 @@ export async function findMetadataForCompanion(companionPath) {
     }
   }
 
-  // 2. Scan all metadata files (new + legacy) for @reference match
+  // 2. Scan all metadata files for @reference match
   for (const entry of entries) {
     if (!isMetadataFile(entry)) continue;
     const metaPath = join(dir, entry);
@@ -241,8 +256,10 @@ export async function findMetadataForCompanion(companionPath) {
 }
 
 /**
- * Rename a file pair (content + metadata) to the ~uid convention after server assigns a UID.
- * Updates @reference values inside the metadata file.
+ * Update the UID field in a metadata file in-place.
+ * Previously renamed the file to include ~uid in the name; now the UID lives
+ * only inside the JSON content, so no rename is needed.
+ *
  * Restores file timestamps from _LastUpdated.
  *
  * @param {Object} meta        - Current metadata object
@@ -250,57 +267,28 @@ export async function findMetadataForCompanion(companionPath) {
  * @param {string} uid         - Newly assigned UID from server
  * @param {string} lastUpdated - Server _LastUpdated value
  * @param {string} serverTz    - Timezone for timestamp conversion
- * @returns {Promise<{ newMetaPath: string, newFilePath: string|null }>}
+ * @returns {Promise<{ newMetaPath: string, newFilePath: null, updatedMeta: Object }>}
  */
 export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, serverTz) {
-  const metaDir = dirname(metaPath);
-  const metaFilename = basename(metaPath);
-
-  // Already in new format — nothing to do
-  if (parseMetaFilename(metaFilename)?.uid === uid) {
-    return { newMetaPath: metaPath, newFilePath: null, updatedMeta: meta };
-  }
-
-  // Determine naturalBase from the temp/old metadata filename
-  // Temp format from adopt.js: "colors.metadata.json" → naturalBase = "colors"
-  // Old tilde format: "colors~uid.metadata.json" → naturalBase = "colors"
-  let naturalBase;
-  const legacyParsed = detectLegacyTildeMetadata(metaFilename);
-  if (legacyParsed) {
-    naturalBase = legacyParsed.naturalBase;
-  } else if (metaFilename.endsWith('.metadata.json')) {
-    naturalBase = metaFilename.slice(0, -'.metadata.json'.length);
-  } else {
-    naturalBase = basename(metaFilename, '.json');
-  }
-
-  const newMetaPath = join(metaDir, buildMetaFilename(naturalBase, uid));
-
-  // Update only the UID field; @reference values are UNCHANGED (companions keep natural names)
   const updatedMeta = { ...meta, UID: uid };
 
-  // Write updated metadata to new path
-  await writeFile(newMetaPath, JSON.stringify(updatedMeta, null, 2) + '\n');
-
-  // Remove old metadata file (new content already written to newMetaPath above)
-  if (metaPath !== newMetaPath) {
-    try { await unlink(metaPath); } catch { /* old file already gone */ }
-  }
+  // Write updated metadata to same path (no rename — UID is in the JSON, not the filename)
+  await writeFile(metaPath, JSON.stringify(updatedMeta, null, 2) + '\n');
 
-  // Restore timestamps for metadata file and companions (companions are not renamed)
+  // Restore timestamps for metadata file and companions
   if (serverTz && lastUpdated) {
     const { setFileTimestamps } = await import('./timestamps.js');
-    try { await setFileTimestamps(newMetaPath, lastUpdated, lastUpdated, serverTz); } catch {}
+    try { await setFileTimestamps(metaPath, lastUpdated, lastUpdated, serverTz); } catch {}
     const contentCols = [...(meta._companionReferenceColumns || meta._contentColumns || [])];
     if (meta._mediaFile) contentCols.push('_mediaFile');
     for (const col of contentCols) {
       const ref = updatedMeta[col];
       if (ref && String(ref).startsWith('@')) {
-        const fp = join(metaDir, String(ref).substring(1));
+        const fp = join(dirname(metaPath), String(ref).substring(1));
         try { await setFileTimestamps(fp, lastUpdated, lastUpdated, serverTz); } catch {}
       }
     }
   }
 
-  return { newMetaPath, newFilePath: null, updatedMeta };
+  return { newMetaPath: metaPath, newFilePath: null, updatedMeta };
 }

package/src/lib/ignore.js

@@ -11,6 +11,9 @@ const DBOIGNORE_FILE = '.dboignore';
 const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
 # (gitignore-style syntax — works like .gitignore)
 
+# Build artifacts
+*.map
+
 # DBO internal
 .app/
 .dboignore