@dboio/cli 0.19.7 → 0.20.3

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, loadRootContentFiles } from '../lib/config.js';
+import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal, addDeleteEntry, loadRootContentFiles, loadRepositoryIntegrationID } from '../lib/config.js';
 import { mergeScriptsConfig, resolveHooks, buildHookEnv, runBuildLifecycle, runPushLifecycle } from '../lib/scripts.js';
-import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket, fetchAndCacheRepositoryIntegration } 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';
@@ -380,8 +380,8 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
     }
   }
 
-  // Toe-stepping check for single-file push
-  if (isToeStepping(options) && meta.UID) {
+  // Toe-stepping check for single-file push (only for records confirmed on server)
+  if (isToeStepping(options) && (meta._CreatedOn || meta._LastUpdated)) {
     const baseline = await loadAppJsonBaseline();
     if (baseline) {
       const appConfig = await loadAppConfig();
@@ -426,7 +426,13 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
   }
   // ── End script hooks ────────────────────────────────────────────────
 
-  const success = await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  const isNewRecord = !meta._CreatedOn && !meta._LastUpdated;
+  let success;
+  if (isNewRecord) {
+    success = await addFromMetadata(meta, metaPath, client, options, modifyKey);
+  } else {
+    success = await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  }
   if (success) {
     const baseline = await loadAppJsonBaseline();
     if (baseline) {
@@ -480,7 +486,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 +499,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 +521,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 +551,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 +622,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.
@@ -671,7 +742,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       continue;
     }
 
-    const isNewRecord = !meta.UID && !meta._id;
+    const isNewRecord = !meta._CreatedOn && !meta._LastUpdated;
 
     // Verify @file references exist
     const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];
@@ -808,19 +879,50 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   // Pre-flight ticket validation (only if no --ticket flag)
   const totalRecords = toPush.length + outputsWithChanges.length + binPushItems.length;
   if (!options.ticket && totalRecords > 0) {
-    const recordSummary = [
-      ...toPush.map(r => { const p = parseMetaFilename(basename(r.metaPath)); return p ? p.naturalBase : basename(r.metaPath, '.metadata.json'); }),
-      ...outputsWithChanges.map(r => basename(r.metaPath, '.json')),
-      ...binPushItems.map(r => `bin:${r.meta.Name}`),
-    ].join(', ');
-    const ticketCheck = await checkStoredTicket(options, `${totalRecords} record(s): ${recordSummary}`);
-    if (ticketCheck.cancel) {
-      log.info('Submission cancelled');
-      return;
+    // Proactive check: fetch RepositoryIntegrationID from the server before prompting.
+    // Uses UpdatedAfter=<today> to keep the response small; the top-level app record is always returned.
+    // Result is cached in .app/config.json so subsequent fetches can fall back to it.
+    let ticketingNeeded = null; // null = unknown (fetch failed)
+    const appConfig = await loadAppConfig();
+    const appShortNameForTicket = appConfig?.AppShortName;
+    if (appShortNameForTicket) {
+      const { id, fetched } = await fetchAndCacheRepositoryIntegration(client, appShortNameForTicket);
+      if (fetched) {
+        // Server answered: null means no RepositoryIntegration configured → skip ticketing
+        ticketingNeeded = (id != null);
+      }
+    }
+
+    // Fallback chain when the server fetch failed or no AppShortName:
+    //   1. Stored RepositoryIntegrationID in .app/config.json (from last successful fetch)
+    //   2. ticketing_required flag in ticketing.local.json (set reactively on first ticket_error)
+    if (ticketingNeeded === null) {
+      const storedId = await loadRepositoryIntegrationID();
+      if (storedId != null) {
+        ticketingNeeded = true;
+      }
+      // If storedId is also null, leave ticketingNeeded as null — checkStoredTicket will
+      // decide based on ticketing_required in ticketing.local.json (reactive fallback).
     }
-    if (ticketCheck.clearTicket) {
-      await clearGlobalTicket();
-      log.dim('  Cleared stored ticket');
+
+    // Skip ticketing entirely when we have a confirmed negative signal
+    if (ticketingNeeded === false) {
+      // RepositoryIntegrationID is null on the server — no ticket needed
+    } else {
+      const recordSummary = [
+        ...toPush.map(r => { const p = parseMetaFilename(basename(r.metaPath)); return p ? p.naturalBase : basename(r.metaPath, '.metadata.json'); }),
+        ...outputsWithChanges.map(r => basename(r.metaPath, '.json')),
+        ...binPushItems.map(r => `bin:${r.meta.Name}`),
+      ].join(', ');
+      const ticketCheck = await checkStoredTicket(options, `${totalRecords} record(s): ${recordSummary}`);
+      if (ticketCheck.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      if (ticketCheck.clearTicket) {
+        await clearGlobalTicket();
+        log.dim('  Cleared stored ticket');
+      }
     }
   }
 
@@ -1116,8 +1218,10 @@ async function pushByUIDs(uids, client, options, modifyKey = null, transactionKe
 }
 
 /**
- * Submit a new record (add) from metadata that has no UID yet.
- * Builds RowID:add1 expressions, submits, then renames files with the returned ~UID.
+ * Submit a new record (insert) from metadata that has no _CreatedOn/_LastUpdated yet.
+ * Builds RowID:add1 expressions and submits. A manually-specified UID (if present in
+ * metadata, placed there by the developer) is included so the server uses that UID.
+ * The server assigns _CreatedOn/_LastUpdated on success, which are written back.
  */
 async function addFromMetadata(meta, metaPath, client, options, modifyKey = null) {
   const entity = meta._entity;
@@ -1129,7 +1233,8 @@ async function addFromMetadata(meta, metaPath, client, options, modifyKey = null
 
   for (const [key, value] of Object.entries(meta)) {
     if (shouldSkipColumn(key)) continue;
-    if (key === 'UID') continue;
+    // UID is included only if the developer manually placed it in the metadata file.
+    // The CLI never auto-generates UIDs — the server assigns them on insert.
     if (value === null || value === undefined) continue;
 
     const strValue = String(value);
@@ -1201,7 +1306,7 @@ async function addFromMetadata(meta, metaPath, client, options, modifyKey = null
     return false;
   }
 
-  // Extract UID from response and rename metadata to ~uid convention
+  // Extract UID and server-populated fields from response, write back to metadata
   const addResults = result.payload?.Results?.Add || result.data?.Payload?.Results?.Add || [];
   if (addResults.length > 0) {
     const returnedUID = addResults[0].UID;
@@ -1221,7 +1326,7 @@ async function addFromMetadata(meta, metaPath, client, options, modifyKey = null
       const config = await loadConfig();
       const serverTz = config.ServerTimezone;
 
-      // Rename metadata file to ~UID convention; companions keep natural names
+      // Write UID and server timestamps back to metadata file; filenames are never renamed
       const renameResult = await renameToUidConvention(meta, metaPath, returnedUID, returnedLastUpdated, serverTz);
 
       // Propagate updated meta back (renameToUidConvention creates a new object)
@@ -1440,24 +1545,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-push UID write: if the record lacked a UID (data record) 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 {
@@ -1578,8 +1678,7 @@ async function checkPathMismatch(meta, metaPath, entity, options) {
   if (!contentFileName) return;
 
   // Compute the current path based on where the file actually is.
-  // Strip the ~UID from the filename — the metadata Path is the canonical
-  // server path and never contains the local ~UID suffix.
+  // Strip any legacy ~UID suffix — the metadata Path is the canonical server path.
   const uid = meta.UID;
   const serverFileName = uid ? stripUidFromFilename(contentFileName, uid) : contentFileName;
   const currentFilePath = join(metaDir, serverFileName);

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() {
@@ -794,6 +794,32 @@ export async function loadTicketSuggestionOutput() {
   } catch { return null; }
 }
 
+/**
+ * Save RepositoryIntegrationID to .app/config.json.
+ * Stores the value fetched from the server's app object.
+ * Pass null to clear (ticketing not required for this app).
+ */
+export async function saveRepositoryIntegrationID(value) {
+  await mkdir(projectDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (value != null) existing.RepositoryIntegrationID = value;
+  else delete existing.RepositoryIntegrationID;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load RepositoryIntegrationID from .app/config.json.
+ * Returns the stored value or null if not set.
+ */
+export async function loadRepositoryIntegrationID() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const val = JSON.parse(raw).RepositoryIntegrationID;
+    return (val != null && val !== '') ? val : null;
+  } catch { return null; }
+}
+
 // ─── Gitignore ────────────────────────────────────────────────────────────
 
 /**
@@ -817,8 +843,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 +903,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 +1192,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/dependencies.js

@@ -289,15 +289,14 @@ export async function syncDependencies(options = {}) {
       await symlinkCredentials(parentProjectDir, checkoutProjectDir);
 
       // 3. Staleness check (unless --force or --schema)
-      if (!forceAll) {
-        // Also check if the checkout is essentially empty (only .app/ exists) —
-        // a previous clone may have failed or been cleaned up, leaving just config
-        let checkoutEmpty = true;
-        try {
-          const entries = await readdir(checkoutDir);
-          checkoutEmpty = entries.every(e => e === '.app' || e.startsWith('.'));
-        } catch { /* dir doesn't exist yet — treat as empty */ }
+      // Track checkoutEmpty here so step 4 can decide whether to use the local schema.
+      let checkoutEmpty = true;
+      try {
+        const entries = await readdir(checkoutDir);
+        checkoutEmpty = entries.every(e => e === '.app' || e.startsWith('.'));
+      } catch { /* dir doesn't exist yet — treat as empty */ }
 
+      if (!forceAll) {
         if (!checkoutEmpty) {
           let isStale = true;
           try {
@@ -314,7 +313,10 @@ export async function syncDependencies(options = {}) {
       }
 
       // 4. Run the clone (quiet — suppress child process output)
-      if (shortname === '_system' && options.systemSchemaPath) {
+      // Use the local schema file only for the very first (empty) checkout — it's a fast path
+      // for pre-bundled schemas. For stale checkouts always fetch from the server so that
+      // newly-added records (e.g. docs added after the schema was saved) are included.
+      if (shortname === '_system' && options.systemSchemaPath && checkoutEmpty) {
         const relPath = relative(checkoutDir, options.systemSchemaPath);
         await execFn(checkoutDir, ['clone', relPath, '--force', '--yes', '--no-deps'], { quiet: true });
       } else {