@dboio/cli 0.19.4 → 0.20.0

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 {

package/src/commands/push.js

@@ -1,18 +1,18 @@
 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';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal, addDeleteEntry } from '../lib/config.js';
+import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal, addDeleteEntry, loadRootContentFiles } from '../lib/config.js';
 import { mergeScriptsConfig, resolveHooks, buildHookEnv, runBuildLifecycle, runPushLifecycle } from '../lib/scripts.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
 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';
@@ -343,6 +343,33 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
       metaPath = found;
       try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
     }
+    if (!meta) {
+      // Last resort: project-wide search for cross-directory @reference.
+      // Handles cases where the companion file is in a different directory from its metadata
+      // (e.g. docs/Operator_Claude.md → lib/extension/Documentation/Operator_Claude.metadata~uid.json).
+      const absoluteFilePath = filePath.startsWith('/') ? filePath : join(process.cwd(), filePath);
+      const ig = await loadIgnore();
+      const allMetaFiles = await findMetadataFiles(process.cwd(), ig);
+      for (const candidatePath of allMetaFiles) {
+        try {
+          const candidateMeta = JSON.parse(await readFile(candidatePath, 'utf8'));
+          const metaDir = dirname(candidatePath);
+          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 (resolved === absoluteFilePath) {
+              metaPath = candidatePath;
+              meta = candidateMeta;
+              break;
+            }
+          }
+        } catch { /* skip unreadable */ }
+        if (meta) break;
+      }
+    }
     if (!meta) {
       // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
       // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
@@ -399,70 +426,187 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
   }
   // ── End script hooks ────────────────────────────────────────────────
 
-  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  const success = await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  if (success) {
+    const baseline = await loadAppJsonBaseline();
+    if (baseline) {
+      await updateBaselineAfterPush(baseline, [{ meta, metaPath, changedColumns: null }]);
+    }
+  }
+  return success;
 }
 /**
- * Ensure manifest.json at project root has companion metadata in lib/bins/app/.
- * Only creates metadata if manifest.json exists at root AND no existing metadata
- * anywhere in the project already references @/manifest.json (prevents duplicates).
+ * Metadata templates for known root content files.
+ * Keyed by filename (case-sensitive). Unknown files in rootContentFiles
+ * get a sensible derived template (extension from name, Public: 0).
  */
-async function ensureManifestMetadata() {
-  // Check if manifest.json exists at project root
-  try {
-    await access(join(process.cwd(), 'manifest.json'));
-  } catch {
-    return; // No manifest.json — nothing to do
-  }
+const ROOT_FILE_TEMPLATES = {
+  'manifest.json': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'JSON',
+    Public: 1,
+    Active: 1,
+    Title: 'PWA Manifest',
+  },
+  'CLAUDE.md': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'MD',
+    Public: 0,
+    Active: 1,
+    Title: 'Claude Code Instructions',
+  },
+  'README.md': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'MD',
+    Public: 1,
+    Active: 1,
+    Title: 'README',
+  },
+};
+
+/**
+ * For each filename in rootContentFiles, ensure a companion metadata file
+ * exists in lib/bins/app/. Skips if the file is absent at root or if metadata
+ * already tracks it. Creates metadata with Content: "@/<filename>" so push
+ * always reads from the project root.
+ */
+async function ensureRootContentFiles() {
+  const rootFiles = await loadRootContentFiles();
+  if (!rootFiles.length) return;
 
-  // Scan the entire project for any metadata file that already references manifest.json.
-  // This prevents creating duplicates when the metadata lives in an unexpected location.
-  // Check both @/manifest.json (root-relative) and @manifest.json (local) references,
-  // as well as Path: manifest.json which indicates a server record for this file.
   const ig = await loadIgnore();
   const allMeta = await findMetadataFiles(process.cwd(), ig);
+
+  // 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) {
     try {
       const raw = await readFile(metaPath, 'utf8');
       const parsed = JSON.parse(raw);
-      if (parsed.Content === '@/manifest.json' || parsed.Content === '@manifest.json') return;
-      if (parsed.Path === 'manifest.json' || parsed.Path === '/manifest.json') return;
+      const content = parsed.Content || '';
+      const path = parsed.Path || '';
+      // Detect both @/filename (root-relative) and @filename (local) references
+      const refName = content.startsWith('@/') ? content.slice(2)
+        : content.startsWith('@') ? content.slice(1)
+        : null;
+      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.
+      if (parsed._entity === 'content' && parsed.Descriptor !== undefined) {
+        const cleaned = { ...parsed };
+        delete cleaned.Descriptor;
+        await writeFile(metaPath, JSON.stringify(cleaned, null, 2) + '\n');
+        log.dim(`  Removed stale Descriptor field from ${basename(metaPath)}`);
+      }
     } catch { /* skip unreadable */ }
   }
 
-  // No existing metadata references manifest.json — create one
   const appConfig = await loadAppConfig();
   const structure = await loadStructureFile();
   const appBin = findBinByPath('app', structure);
-
   const binsAppDir = join(process.cwd(), BINS_DIR, 'app');
-  await mkdir(binsAppDir, { recursive: true });
 
-  const meta = {
-    _entity: 'content',
-    _companionReferenceColumns: ['Content'],
-    Content: '@/manifest.json',
-    Path: 'manifest.json',
-    Name: 'manifest.json',
-    Extension: 'JSON',
-    Public: 1,
-    Active: 1,
-    Title: 'PWA Manifest',
-  };
+  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 (case-insensitive)
+    if (tracked.has(filename.toLowerCase())) continue;
+
+    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'),
+      Public: 0,
+      Active: 1,
+      Title: filename,
+    };
+
+    const meta = {
+      ...tmpl,
+      Content: `@/${filename}`,
+      Path: filename,
+      Name: filename,
+    };
+    if (appBin) meta.BinID = appBin.binId;
+    if (appConfig.AppID) meta.AppID = appConfig.AppID;
+
+    await mkdir(binsAppDir, { recursive: true });
+    const stem = filename.replace(/\.[^.]+$/, '');
+    const metaFilename = `${stem}.metadata.json`;
+    await writeFile(join(binsAppDir, metaFilename), JSON.stringify(meta, null, 2) + '\n');
+    log.info(`Auto-created ${metaFilename} for ${filename}`);
+  }
+}
 
-  if (appBin) meta.BinID = appBin.binId;
-  if (appConfig.AppID) meta.AppID = appConfig.AppID;
+/**
+ * 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;
+}
 
-  const metaPath = join(binsAppDir, 'manifest.metadata.json');
-  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
-  log.info('Auto-created manifest.metadata.json for manifest.json');
+/**
+ * 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)
  */
 async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID', deletedCount = 0) {
-  // Auto-create manifest.metadata.json if manifest.json exists at root without companion metadata
-  await ensureManifestMetadata();
+  // Auto-create metadata for root content files (manifest.json, CLAUDE.md, README.md, etc.)
+  await ensureRootContentFiles();
 
   // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
   // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
@@ -472,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.
@@ -1353,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 {
@@ -1378,12 +1525,14 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     if (editResults.length > 0) {
       const updated = editResults[0]._LastUpdated || editResults[0].LastUpdated;
       if (updated) {
+        // Always update _LastUpdated in memory and on disk (required for baseline sync
+        // even when ServerTimezone is not configured)
+        meta._LastUpdated = updated;
+        await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
         const config = await loadConfig();
         const serverTz = config.ServerTimezone;
         if (serverTz) {
-          // Update metadata _LastUpdated and set file mtime
-          meta._LastUpdated = updated;
-          await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+          // Set file mtimes to server timestamp (requires timezone for correct conversion)
           await setFileTimestamps(metaPath, meta._CreatedOn, updated, serverTz);
           // Update content file mtime too
           const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];

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

@@ -173,6 +173,20 @@ export async function updateConfigWithApp({ AppID, AppUID, AppName, AppShortName
   await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
 }
 
+/**
+ * Persist the UserMedia preference to .app/config.json.
+ * @param {boolean} value - true = download user media, false = skip
+ */
+export async function updateConfigUserMedia(value) {
+  await mkdir(projectDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  existing.UserMedia = value;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
 // ─── Dependency helpers ───────────────────────────────────────────────────
 
 /**
@@ -513,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() {
@@ -803,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');
@@ -813,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 + addition);
-  for (const p of toAdd) log.dim(`  Added ${p} to .gitignore`);
+  await writeFile(gitignorePath, content + prefix + outputLines.join('\n') + '\n');
+
+  const added = outputLines.filter(l => l.trim() !== '' && !l.startsWith('#'));
+  for (const p of added) log.dim(`  Added ${p} to .gitignore`);
 }
 
 // ─── Baseline (.app/<shortName>.json) ─────────────────────────────────────
@@ -1070,6 +1164,39 @@ export async function loadScriptsLocal() {
   }
 }
 
+// ─── Root Content Files ───────────────────────────────────────────────────────
+
+const ROOT_CONTENT_FILES_DEFAULTS = ['CLAUDE.md', 'README.md', 'manifest.json', 'package.json', '.dboignore', '.gitignore'];
+
+/**
+ * Load rootContentFiles from .app/config.json.
+ * If the key is absent, writes the defaults and returns them.
+ * If the key is [], false, or null, returns [] (disabled).
+ */
+export async function loadRootContentFiles() {
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (!('rootContentFiles' in existing)) {
+    await saveRootContentFiles(ROOT_CONTENT_FILES_DEFAULTS);
+    return ROOT_CONTENT_FILES_DEFAULTS;
+  }
+  const val = existing.rootContentFiles;
+  if (!val || (Array.isArray(val) && val.length === 0)) return [];
+  return Array.isArray(val) ? val : [];
+}
+
+/**
+ * Persist rootContentFiles to .app/config.json.
+ * Pass [] to disable root content file tracking.
+ */
+export async function saveRootContentFiles(list) {
+  await mkdir(projectDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  existing.rootContentFiles = list;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
 // ─── Tag Config ───────────────────────────────────────────────────────────────
 
 /**