@dboio/cli 0.20.0 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.20.0",
+  "version": "0.20.3",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/plugins/claude/dbo/docs/dual-platform-maintenance.md

@@ -0,0 +1,135 @@
+# Dual-Platform Maintenance Strategy
+
+## Overview
+
+The dbo.io API runs on two parallel codebases during the .NET Core migration period:
+
+- **`src/webapp-framework/`** — ASP.NET 4.7.2 (Windows), the current production platform
+- **`src/webapp-core/`** — .NET Core 8 (Linux), functionally tested, being prepared for production
+
+Both share identical `App_Code/` directories containing all business logic (~249 .cs files). Going forward, new feature work must be applied to both codebases until webapp-framework is retired.
+
+## File Structure
+
+### Shared Code (`App_Code/dboio/`)
+
+These directories exist in both `webapp-framework` and `webapp-core` and must stay in sync for feature changes:
+
+- `Data/` — entities, data sources, API add-ons, app operations, output/query system
+- `Data/App/` — AppManager, application-level operations
+- `Data/DataSource/` — MySQL, SQL Server, ODBC data source implementations
+- `Data/Output/` — output rendering, query building
+- `Web/Controllers/` — all MVC/API controllers
+- `Web/Security/` — authentication, authorization, SAML
+- `Web/` — caching (ICacheProvider, Redis, HttpRuntime), session, delivery pipeline
+- `Util/` — encryption, email, file/zip utilities
+
+### webapp-framework Only (Windows)
+
+- `App_Start/` — legacy ASP.NET startup
+- `Web.config` + `web.*.config` — IIS configuration files
+- `Global.asax` / `Global.asax.cs` — application lifecycle
+- `Account/` — legacy account pages
+
+### webapp-core Only (Linux)
+
+- `Program.cs` — .NET Core entry point and middleware pipeline
+- `Middleware/` — 9 middleware classes (ported from HttpModules)
+- `Shims/` — compatibility shims (HttpContext, Cache, ConfigurationManager, CaseInsensitiveFileProvider)
+- `appsettings.json` / `appsettings.*.json` — .NET Core configuration
+- `log4net.config` — Core-specific logging configuration
+
+## Change Categories
+
+### Category 1: Core-Only Infrastructure
+
+Changes that only apply to `webapp-core`. No transfer to `webapp-framework` needed.
+
+Examples:
+- Middleware files (`Middleware/*.cs`)
+- Shim files (`Shims/*.cs`)
+- `Program.cs`
+- `appsettings*.json`, `log4net.config`
+- `App_Code/Properties/AssemblyInfo.cs` (platform-diverged)
+- `App_Code/Global.asax.cs` (platform-diverged)
+- Build/deploy scripts (`build/deploy-core.sh`, `build/boot-deploy.sh`)
+- AWS infrastructure (EFS, CloudWatch, Launch Templates)
+
+When a transfer review issue is created for Category 1 files, close it as "not planned."
+
+### Category 2: Shared Business Logic
+
+Changes to business logic in `App_Code/dboio/` that affect both platforms.
+
+Examples:
+- Entity classes, data access (`Data/`, `Data/App/`, `Data/DataSource/`)
+- Controllers (`Web/Controllers/`)
+- Security (`Web/Security/`)
+- Cache logic (`Web/` cache providers)
+- Utility classes (`Util/`)
+- Any bug fix or feature in shared code
+
+When a transfer review issue is created for Category 2 files, apply the equivalent change to `src/webapp-framework/App_Code/`, then close the issue.
+
+## Automated Transfer Review Workflow
+
+A GitHub Action (`.github/workflows/transfer-review.yml`) monitors pushes to all branches.
+
+### How it works
+
+1. Triggers on any push that modifies files under `src/webapp-core/App_Code/`
+2. Filters out excluded subdirectories (configurable in the workflow YAML)
+3. Creates a GitHub issue labeled `netcore-aspnet-transfer`
+4. Lists all changed App_Code files, the commit hash, branch, and author
+
+### Reviewing transfer issues
+
+1. Open the issue and review the changed files
+2. If all changes are Category 1 (Core-only): close as "not planned"
+3. If any changes are Category 2 (shared): apply to `webapp-framework`, then close with a reference to the transfer commit
+
+### Exclusion list
+
+The workflow YAML contains an `EXCLUDE_PATTERNS` array. Add subdirectory names to suppress issues for known Core-only paths within `App_Code/`:
+
+```bash
+EXCLUDE_PATTERNS=(
+  # "Properties"
+  # Add more as patterns emerge
+)
+```
+
+## Commit Message Conventions
+
+No strict format required, but these prefixes help identify change scope:
+
+- **`webapp-core:`** — Core-only changes (Category 1, no transfer needed)
+- **`webapp-framework:`** — Framework-only changes
+- **No prefix** — changes that apply to both platforms, or general feature work
+
+Examples:
+- `webapp-core: fix middleware ordering for auth` (Category 1)
+- `Task XXXX | entity: add new validation rule #NNN` (Category 2, needs transfer)
+
+## Development Flow
+
+1. New business logic typically starts in `webapp-framework` (production platform)
+2. After committing, manually apply the same change to `webapp-core`
+3. Core-only infrastructure work happens only in `webapp-core`
+4. The transfer review workflow catches the reverse case (Core-first changes that may need Framework transfer)
+
+## Retirement Criteria for webapp-framework
+
+`webapp-framework` can be retired when ALL of the following are met:
+
+1. **Functional parity** — webapp-core handles all production traffic without regressions
+2. **Production cutover** — load balancer routes 100% of traffic to Core servers
+3. **Stability period** — at least 30 days of production traffic on Core with no regressions
+4. **Client sign-off** — explicit approval to decommission Windows servers
+5. **Rollback plan verified** — confirmed ability to revert to webapp-framework if needed
+
+After retirement:
+- Archive `src/webapp-framework/` (do not delete immediately)
+- Remove the transfer review workflow
+- Remove the `netcore-aspnet-transfer` label
+- Update this document

package/src/commands/adopt.js

@@ -93,9 +93,10 @@ const ROOT_FILE_TEMPLATES = {
  */
 async function buildBinMetadata(filePath, entity, appConfig, structure) {
   const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
-  const ext = extname(filePath).replace('.', '').toLowerCase();
   const fileName = basename(filePath);
-  const base = basename(filePath, extname(filePath));
+  const ext = extname(filePath).replace('.', '').toLowerCase();
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || fileName; // dotfiles (.dboignore): rawBase='' → use full filename
   const fileDir = dirname(rel);
   const bin = findBinByPath(fileDir, structure);
   const binPath = bin?.path || '';
@@ -103,9 +104,9 @@ async function buildBinMetadata(filePath, entity, appConfig, structure) {
   const metaPath = join(dirname(filePath), `${base}.metadata.json`);
 
   if (entity === 'content') {
-    const contentPath = binPath
-      ? `${binPath}/${base}.${ext}`
-      : `${base}.${ext}`;
+    // For dotfiles, base === fileName (no real ext), so path = base; otherwise base.ext
+    const localName = (base === fileName) ? fileName : `${base}.${ext}`;
+    const contentPath = binPath ? `${binPath}/${localName}` : localName;
     const meta = {
       _entity: 'content',
       _companionReferenceColumns: ['Content'],
@@ -165,7 +166,7 @@ async function adoptSingleFile(filePath, entityArg, options) {
     const appBin = findBinByPath('app', structure);
     const binsAppDir = join(process.cwd(), BINS_DIR, 'app');
     const ext = extname(fileName).replace('.', '').toUpperCase() || 'TXT';
-    const stem = basename(fileName, extname(fileName));
+    const stem = fileName;
 
     const metaFilename = `${stem}.metadata.json`;
     const metaPath = join(binsAppDir, metaFilename);
@@ -174,15 +175,15 @@ async function adoptSingleFile(filePath, entityArg, options) {
     let existingMeta = null;
     try { existingMeta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
     if (existingMeta) {
-      if (existingMeta.UID || existingMeta._CreatedOn) {
-        log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+      if (existingMeta._CreatedOn || existingMeta._LastUpdated) {
+        log.warn(`"${fileName}" is already on the server (_CreatedOn/_LastUpdated present) — skipping.`);
         return;
       }
       if (!options.yes) {
         const inquirer = (await import('inquirer')).default;
         const { overwrite } = await inquirer.prompt([{
           type: 'confirm', name: 'overwrite',
-          message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+          message: `Metadata already exists for "${fileName}" (not yet on server). Overwrite?`,
           default: false,
         }]);
         if (!overwrite) return;
@@ -215,8 +216,8 @@ async function adoptSingleFile(filePath, entityArg, options) {
   }
 
   const dir = dirname(filePath);
-  const ext = extname(filePath);
-  const base = basename(filePath, ext);
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || basename(filePath); // dotfiles: '' → full filename
 
   // Check for existing metadata
   const metaPath = join(dir, `${base}.metadata.json`);
@@ -226,17 +227,17 @@ async function adoptSingleFile(filePath, entityArg, options) {
   } catch { /* no file — that's fine */ }
 
   if (existingMeta) {
-    if (existingMeta.UID || existingMeta._CreatedOn) {
-      log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+    if (existingMeta._CreatedOn || existingMeta._LastUpdated) {
+      log.warn(`"${fileName}" is already on the server (_CreatedOn/_LastUpdated present) — skipping.`);
       return;
     }
-    // Metadata exists but no server record
+    // Metadata exists but record not yet on server
     if (!options.yes) {
       const inquirer = (await import('inquirer')).default;
       const { overwrite } = await inquirer.prompt([{
         type: 'confirm',
         name: 'overwrite',
-        message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+        message: `Metadata already exists for "${fileName}" (not yet on server). Overwrite?`,
         default: false,
       }]);
       if (!overwrite) return;
@@ -355,7 +356,8 @@ async function adoptSingleFile(filePath, entityArg, options) {
 async function runInteractiveWizard(filePath, options) {
   const inquirer = (await import('inquirer')).default;
   const fileName = basename(filePath);
-  const base = basename(filePath, extname(filePath));
+  const rawBase = basename(filePath, extname(filePath));
+  const base = rawBase || fileName; // dotfiles: '' → full filename
   const metaPath = join(dirname(filePath), `${base}.metadata.json`);
 
   log.plain('');

package/src/commands/clone.js

@@ -14,7 +14,7 @@ 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';
 import { fetchSchema, loadSchema, saveSchema, isSchemaStale } from '../lib/schema.js';
-import { appMetadataPath } from '../lib/config.js';
+import { appMetadataPath, baselinePath, metadataSchemaPath } from '../lib/config.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 import { upsertDeployEntry } from '../lib/deploy-config.js';
 import { syncDependencies, parseDependenciesColumn } from '../lib/dependencies.js';
@@ -250,6 +250,114 @@ export async function detectAndTrashOrphans(appJson, ig, sync, options) {
   }
 }
 
+/**
+ * Use the explicit `appJson.deleted` map (returned by the server in delta/baseline responses)
+ * to find and trash local files for records the server has deleted.
+ *
+ * Unlike detectAndTrashOrphans() which diffs all local UIDs against all server UIDs,
+ * this function is authoritative: if the server says a UID was deleted, it moves the
+ * local files immediately — no full UID scan needed. This makes it safe to call in
+ * pull/delta mode where appJson.children may only contain changed records.
+ *
+ * @param {object} appJson  - App JSON possibly containing a `deleted` map
+ * @param {import('ignore').Ignore} ig - Ignore instance for findMetadataFiles
+ * @param {object} sync     - Parsed synchronize.json { delete, edit, add }
+ * @param {object} options  - Clone options
+ */
+export async function trashServerDeletedRecords(appJson, ig, sync, options) {
+  if (options.entityFilter) return;
+  if (!appJson?.deleted || typeof appJson.deleted !== 'object') return;
+
+  // Build set of UIDs to trash from all entities in deleted map
+  const deletedUids = new Map(); // uid → { entity, name }
+  for (const [entity, entries] of Object.entries(appJson.deleted)) {
+    if (!Array.isArray(entries)) continue;
+    for (const entry of entries) {
+      if (entry?.UID) {
+        deletedUids.set(String(entry.UID), { entity, name: entry.Name || entry.UID });
+      }
+    }
+  }
+
+  if (deletedUids.size === 0) return;
+
+  // UIDs already queued for deletion in synchronize.json — skip them
+  const stagedDeleteUids = new Set(
+    (sync.delete || []).map(e => e.UID).filter(Boolean).map(String)
+  );
+
+  const metaFiles = await findMetadataFiles(process.cwd(), ig);
+  if (metaFiles.length === 0) return;
+
+  const trashDir = join(process.cwd(), 'trash');
+  const toTrash = [];
+
+  for (const metaPath of metaFiles) {
+    let meta;
+    try {
+      meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!meta.UID) continue;
+    const uid = String(meta.UID);
+    if (!deletedUids.has(uid)) continue;
+    if (stagedDeleteUids.has(uid)) continue;
+
+    const metaDir = dirname(metaPath);
+    const filesToMove = [metaPath];
+
+    for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
+      const ref = meta[col];
+      if (ref && String(ref).startsWith('@')) {
+        const refName = String(ref).substring(1);
+        const companionPath = refName.startsWith('/')
+          ? join(process.cwd(), refName)
+          : join(metaDir, refName);
+        if (await fileExists(companionPath)) filesToMove.push(companionPath);
+      }
+    }
+
+    if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+      const refName = String(meta._mediaFile).substring(1);
+      const mediaPath = refName.startsWith('/')
+        ? join(process.cwd(), refName)
+        : join(metaDir, refName);
+      if (await fileExists(mediaPath)) filesToMove.push(mediaPath);
+    }
+
+    const { entity } = deletedUids.get(uid);
+    toTrash.push({ metaPath, uid, entity, filesToMove });
+  }
+
+  if (toTrash.length === 0) return;
+
+  await mkdir(trashDir, { recursive: true });
+
+  let trashed = 0;
+  for (const { metaPath, uid, entity, filesToMove } of toTrash) {
+    log.dim(`  Trashed (server deleted): ${basename(metaPath)} (${entity}:${uid})`);
+    for (const filePath of filesToMove) {
+      const destBase = basename(filePath);
+      let destPath = join(trashDir, destBase);
+      try { await stat(destPath); destPath = `${destPath}.${Date.now()}`; } catch {}
+      try {
+        await rename(filePath, destPath);
+        trashed++;
+      } catch (err) {
+        log.warn(`  Could not trash: ${filePath} — ${err.message}`);
+      }
+    }
+  }
+
+  if (trashed > 0) {
+    await ensureTrashIcon(trashDir);
+    log.plain('');
+    log.warn(`Moved ${toTrash.length} server-deleted record(s) to trash`);
+  }
+}
+
 /**
  * Resolve a content Path to a directory under Bins/.
  *
@@ -353,8 +461,9 @@ 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.json
-  const metaPath = join(dir, buildMetaFilename(name));
+  // Metadata: filename.metadata.json (includes extension to avoid collisions between records
+  // with the same Name but different Extension, e.g. codeTest.js vs codeTest.css)
+  const metaPath = join(dir, buildMetaFilename(filename));
 
   return { dir, filename, metaPath };
 }
@@ -1232,7 +1341,24 @@ export async function performClone(source, options = {}) {
   // 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 });
+    // If the app's ShortName changed, rename the .app/ files that are keyed by it
+    // before updating config so the old paths can still be resolved.
+    const oldShortName = config.AppShortName;
+    const newShortName = appJson.ShortName;
+    if (oldShortName && oldShortName !== newShortName) {
+      const oldBaseline = await baselinePath();
+      const oldAppMeta = await appMetadataPath();
+      const oldSchema  = await metadataSchemaPath();
+      await updateConfigWithApp({ AppShortName: newShortName });
+      const newBaseline = await baselinePath();
+      const newAppMeta  = await appMetadataPath();
+      const newSchema   = await metadataSchemaPath();
+      for (const [oldPath, newPath] of [[oldBaseline, newBaseline], [oldAppMeta, newAppMeta], [oldSchema, newSchema]]) {
+        try { await access(oldPath); await rename(oldPath, newPath); log.dim(`  Renamed ${basename(oldPath)} → ${basename(newPath)}`); } catch { /* file absent, nothing to rename */ }
+      }
+    } else {
+      await updateConfigWithApp({ AppShortName: newShortName });
+    }
   }
 
   // Regenerate metadata_schema.json for any new entity types
@@ -1525,6 +1651,9 @@ export async function performClone(source, options = {}) {
   if (!entityFilter) {
     const ig = await loadIgnore();
     const sync = await loadSynchronize();
+    // Use explicit deleted list from server first (authoritative, works in delta/pull mode)
+    await trashServerDeletedRecords(appJson, ig, sync, { ...options, entityFilter });
+    // Fall back to full UID diff for records absent from server but not in deleted list
     await detectAndTrashOrphans(appJson, ig, sync, { ...options, entityFilter });
   }
 
@@ -2075,7 +2204,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     // Skip __WILL_DELETE__-prefixed files — treat as "no existing file"
     const willDeleteEntityMeta = join(dirName, `${WILL_DELETE_PREFIX}${basename(metaPath)}`);
     const entityMetaExists = await fileExists(metaPath) && !await fileExists(willDeleteEntityMeta);
-    if (entityMetaExists && !options.yes && !hasNewExtractions) {
+    if (entityMetaExists && !options.yes && !options.force && !hasNewExtractions) {
       if (bulkAction.value === 'skip_all') {
         log.dim(`  Skipped ${name}`);
         refs.push({ uid: record.UID, metaPath });
@@ -3389,7 +3518,8 @@ 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.json; usedNames retained for non-UID edge case tracking
+  // Metadata: filename.metadata.json (includes extension to avoid collisions between records
+  // with the same Name but different Extension, e.g. codeTest.js vs codeTest.css)
   const nameKey = `${dir}/${name}`;
   usedNames.set(nameKey, (usedNames.get(nameKey) || 0) + 1);
 
@@ -3401,7 +3531,20 @@ async function processRecord(entityName, record, structure, options, usedNames,
   );
 
   const filePath = join(dir, fileName);
-  const metaPath = join(dir, buildMetaFilename(name));
+  const metaPath = join(dir, buildMetaFilename(fileName));
+
+  // Legacy migration: rename old name.metadata.json → new filename.metadata.json
+  // (repos cloned before this fix used the base name without extension as the metadata stem)
+  const legacyMetaPath = join(dir, buildMetaFilename(name));
+  if (legacyMetaPath !== metaPath && !await fileExists(metaPath) && await fileExists(legacyMetaPath)) {
+    try {
+      const legacyMeta = JSON.parse(await readFile(legacyMetaPath, 'utf8'));
+      if (legacyMeta.UID === uid) {
+        const { rename: fsRename } = await import('fs/promises');
+        await fsRename(legacyMetaPath, metaPath);
+      }
+    } catch { /* non-critical */ }
+  }
 
   // Rename legacy ~UID companion files to natural names if needed
   if (await fileExists(metaPath)) {
@@ -4431,8 +4574,18 @@ async function _generateRootFileStub(filename, appJson) {
   }
 
   if (filenameLower === 'claude.md') {
+    const cfg = await loadConfig();
+    const domain = cfg.domain || '';
+    const appShortName = appJson.ShortName || '';
+    const siteRecords = appJson.children?.site || [];
+    const siteLines = siteRecords.map(s => {
+      const url = `//${domain}/app/${appShortName}/${s.ShortName}`;
+      const label = s.Title || s.Name || s.ShortName;
+      return `- \`${url}\` — ${label} (add \`?dev=true\` to serve uncompiled JS; add \`&console=true\` for verbose debug logging)`;
+    });
     const stub = [
       `# ${appName}`,
+      ...(siteLines.length > 0 ? [``, `## App Sites`, ``, ...siteLines] : []),
       ``,
       `## DBO CLI`,
       ``,
@@ -4478,7 +4631,19 @@ async function _generateRootFileStub(filename, appJson) {
   }
 
   if (filenameLower === 'readme.md') {
+    const cfg = await loadConfig();
+    const domain = cfg.domain || '';
+    const appShortName = appJson.ShortName || '';
+    const siteRecords = appJson.children?.site || [];
     const parts = [`# ${appName}`];
+    if (siteRecords.length > 0) {
+      parts.push('');
+      for (const s of siteRecords) {
+        const url = `//${domain}/app/${appShortName}/${s.ShortName}`;
+        const label = s.Title || s.Name || s.ShortName;
+        parts.push(`- [${label}](${url})`);
+      }
+    }
     if (description) parts.push('', description);
     parts.push('');
     await writeFile(rootPath, parts.join('\n'));

package/src/commands/push.js

@@ -6,9 +6,9 @@ import { buildInputBody, checkSubmitErrors, getSessionUserOverride } from '../li
 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';
@@ -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) {
@@ -736,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 || [];
@@ -873,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');
+      }
     }
   }
 
@@ -1181,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;
@@ -1194,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);
@@ -1266,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;
@@ -1286,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)
@@ -1505,7 +1545,7 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   // Clean up per-record ticket on success
   await clearRecordTicket(uid || id);
 
-  // Post-insert UID write: 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 || [];
@@ -1638,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/lib/config.js

@@ -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 ────────────────────────────────────────────────────────────
 
 /**

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 {

package/src/lib/input-parser.js

@@ -37,12 +37,8 @@ export async function buildInputBody(dataExpressions, extraParams = {}) {
   }
 
   for (const expr of dataExpressions) {
-    // Split by & to handle multiple ops in one -d string
-    const ops = expr.split('&');
-    for (const op of ops) {
-      const encoded = await encodeInputExpression(op.trim());
-      parts.push(encoded);
-    }
+    const encoded = await encodeInputExpression(expr.trim());
+    parts.push(encoded);
   }
 
   return parts.join('&');

package/src/lib/insert.js

@@ -283,7 +283,8 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
 
   for (const [key, value] of Object.entries(meta)) {
     if (shouldSkipColumn(key)) continue;
-    if (key === 'UID') continue; // Never submit UID on add — server assigns it
+    // 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);
@@ -481,8 +482,8 @@ export async function findUnaddedFiles(dir, ig, referencedFiles) {
       const raw = await readFile(join(dir, entry.name), 'utf8');
       if (!raw.trim()) continue;
       const meta = JSON.parse(raw);
-      // Only count records that are on the server (have UID or _CreatedOn)
-      if (!meta.UID && !meta._CreatedOn) continue;
+      // Only count records that are on the server (have _CreatedOn or _LastUpdated)
+      if (!meta._CreatedOn && !meta._LastUpdated) continue;
       collectCompanionRefs(meta, localRefs);
     } catch { /* skip unreadable */ }
   }
@@ -550,7 +551,7 @@ async function _scanMetadataRefs(dir, referenced) {
       const raw = await readFile(fullPath, 'utf8');
       if (!raw.trim()) continue;
       const meta = JSON.parse(raw);
-      if (!meta._CreatedOn && !meta.UID) continue; // only count server-confirmed records
+      if (!meta._CreatedOn && !meta._LastUpdated) continue; // only count server-confirmed records
 
       // Collect all @ references (including from inline output children)
       const allRefs = new Set();

package/src/lib/ticketing.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { log } from './logger.js';
-import { projectDir } from './config.js';
+import { projectDir, saveRepositoryIntegrationID, loadRepositoryIntegrationID } from './config.js';
 
 const TICKETING_FILE = 'ticketing.local.json';
 
@@ -309,3 +309,59 @@ export async function applyStoredTicketToSubmission(dataExprs, entity, rowId, ui
   }
   return null;
 }
+
+/**
+ * Fetch the app object from the server and cache RepositoryIntegrationID in .app/config.json.
+ *
+ * Uses UpdatedAfter=<today> to keep the response small — children records are filtered
+ * but the top-level app record (including RepositoryIntegrationID) is always returned.
+ *
+ * @param {DboClient} client
+ * @param {string} appShortName
+ * @returns {Promise<{ id: string|null, fetched: boolean }>}
+ *   id: the RepositoryIntegrationID value (or null if not set)
+ *   fetched: true if the server responded successfully, false on network/parse failure
+ */
+export async function fetchAndCacheRepositoryIntegration(client, appShortName) {
+  if (!appShortName) return { id: null, fetched: false };
+
+  try {
+    const today = new Date().toISOString().substring(0, 10); // YYYY-MM-DD
+    const result = await client.get(
+      `/api/app/object/${encodeURIComponent(appShortName)}`,
+      { UpdatedAfter: today }
+    );
+
+    if (!result.ok && !result.successful) return { id: null, fetched: false };
+
+    const data = result.payload || result.data;
+    if (!data) return { id: null, fetched: false };
+
+    // Normalize response shape (array, Rows wrapper, or direct object)
+    let appRecord;
+    if (Array.isArray(data)) {
+      appRecord = data.length > 0 ? data[0] : null;
+    } else if (data?.Rows?.length > 0) {
+      appRecord = data.Rows[0];
+    } else if (data?.rows?.length > 0) {
+      appRecord = data.rows[0];
+    } else if (data && typeof data === 'object' && (data.UID || data.ShortName)) {
+      appRecord = data;
+    } else {
+      return { id: null, fetched: false };
+    }
+
+    if (!appRecord) return { id: null, fetched: false };
+
+    const id = (appRecord.RepositoryIntegrationID != null && appRecord.RepositoryIntegrationID !== '')
+      ? appRecord.RepositoryIntegrationID
+      : null;
+
+    // Persist so push can fall back to this if the next fetch fails
+    await saveRepositoryIntegrationID(id);
+
+    return { id, fetched: true };
+  } catch {
+    return { id: null, fetched: false };
+  }
+}

package/src/lib/toe-stepping.js

@@ -1,11 +1,11 @@
 import chalk from 'chalk';
 import { dirname, basename, join } from 'path';
-import { readFile } from 'fs/promises';
-import { findBaselineEntry, shouldSkipColumn, normalizeValue, isReference, resolveReferencePath } from './delta.js';
+import { readFile, writeFile } from 'fs/promises';
+import { findBaselineEntry, shouldSkipColumn, normalizeValue, isReference, resolveReferencePath, saveBaseline } from './delta.js';
 import { resolveContentValue } from '../commands/clone.js';
 import { computeLineDiff, formatDiff } from './diff.js';
 import { parseMetaFilename } from './filenames.js';
-import { parseServerDate } from './timestamps.js';
+import { parseServerDate, setFileTimestamps } from './timestamps.js';
 import { log } from './logger.js';
 
 /**
@@ -335,6 +335,7 @@ export async function checkToeStepping(records, client, baseline, options, appSh
   let skippedUIDs = new Set();
   let bulkAction = null; // 'push_all' | 'skip_all'
   let hasConflicts = false;
+  let baselineModified = false;
 
   for (const { meta, metaPath } of records) {
     const uid = meta.UID;
@@ -381,6 +382,14 @@ export async function checkToeStepping(records, client, baseline, options, appSh
     if (options.yes || bulkAction === 'push_all') {
       continue; // push this record
     }
+    if (bulkAction === 'pull_all') {
+      await applyServerToLocal(serverEntry, meta, metaPath, serverTz);
+      _updateBaselineEntry(baseline, entity, uid, serverEntry);
+      baselineModified = true;
+      log.success(`  Pulled server version of "${label}" to local`);
+      skippedUIDs.add(uid);
+      continue;
+    }
     if (bulkAction === 'skip_all') {
       skippedUIDs.add(uid);
       continue;
@@ -395,9 +404,11 @@ export async function checkToeStepping(records, client, baseline, options, appSh
         message: `"${label}" has server changes. How to proceed?`,
         choices: [
           { name: 'Push anyway (overwrite server changes)', value: 'push' },
+          { name: 'Pull from server (overwrite local changes)', value: 'pull' },
           { name: 'Compare differences', value: 'compare' },
           { name: 'Skip this record', value: 'skip' },
           { name: 'Push all remaining (overwrite all)', value: 'push_all' },
+          { name: 'Pull all remaining (overwrite all local)', value: 'pull_all' },
           { name: 'Skip all remaining', value: 'skip_all' },
           { name: 'Cancel entire push', value: 'cancel' },
         ],
@@ -414,6 +425,14 @@ export async function checkToeStepping(records, client, baseline, options, appSh
       log.info('Push cancelled. Run "dbo pull" to fetch server changes first.');
       return false;
     }
+    if (action === 'pull' || action === 'pull_all') {
+      await applyServerToLocal(serverEntry, meta, metaPath, serverTz);
+      _updateBaselineEntry(baseline, entity, uid, serverEntry);
+      baselineModified = true;
+      log.success(`  Pulled server version of "${label}" to local`);
+      skippedUIDs.add(uid);
+      if (action === 'pull_all') bulkAction = 'pull_all';
+    }
     if (action === 'skip' || action === 'skip_all') {
       skippedUIDs.add(uid);
       if (action === 'skip_all') bulkAction = 'skip_all';
@@ -423,6 +442,12 @@ export async function checkToeStepping(records, client, baseline, options, appSh
     }
   }
 
+  if (baselineModified) {
+    try {
+      await saveBaseline(baseline);
+    } catch { /* non-critical — next push will re-detect */ }
+  }
+
   if (!hasConflicts) return true;
 
   // Return skipped UIDs so the caller can filter them out
@@ -496,3 +521,78 @@ async function showPushDiff(serverEntry, localMeta, metaPath) {
 
   log.plain('');
 }
+
+/**
+ * Update the in-memory baseline entry for a record with the server's current
+ * values. Called after pulling from server so the next toe-stepping check
+ * sees the pulled state as the new baseline and does not re-raise the conflict.
+ *
+ * @param {Object} baseline    - Loaded baseline object (mutated in place)
+ * @param {string} entity      - Entity type (e.g., "content")
+ * @param {string} uid         - Record UID
+ * @param {Object} serverEntry - Live server record
+ */
+function _updateBaselineEntry(baseline, entity, uid, serverEntry) {
+  if (!baseline?.children) return;
+  const arr = baseline.children[entity];
+  if (!Array.isArray(arr)) return;
+  const idx = arr.findIndex(e => e.UID === uid);
+  if (idx < 0) return;
+
+  const SKIP = new Set(['_entity', '_companionReferenceColumns', '_contentColumns',
+    '_mediaFile', '_pathConfirmed', 'children', '_id']);
+  for (const [col, rawVal] of Object.entries(serverEntry)) {
+    if (SKIP.has(col)) continue;
+    const decoded = resolveContentValue(rawVal);
+    arr[idx][col] = decoded !== null ? decoded : rawVal;
+  }
+}
+
+/**
+ * Overwrite local metadata and companion content files with server values.
+ *
+ * Called when the user chooses "Pull from server" during conflict resolution.
+ * Updates:
+ *   - companion content files (columns listed in _companionReferenceColumns)
+ *   - all non-system metadata fields
+ *   - _LastUpdated / _CreatedOn timestamps in the metadata JSON
+ *   - file timestamps on both the metadata file and any companion files
+ *
+ * @param {Object} serverEntry - Live server record (from fetchServerRecord*)
+ * @param {Object} localMeta   - Currently loaded metadata object
+ * @param {string} metaPath    - Absolute path to the .metadata.json file
+ * @param {string} [serverTz]  - Server timezone string (e.g. "America/Chicago")
+ */
+async function applyServerToLocal(serverEntry, localMeta, metaPath, serverTz) {
+  const metaDir = dirname(metaPath);
+  const companions = new Set(localMeta._companionReferenceColumns || []);
+
+  // Write companion content files from server values
+  for (const col of companions) {
+    const ref = localMeta[col];
+    if (!ref || !String(ref).startsWith('@')) continue;
+    const filePath = join(metaDir, String(ref).substring(1));
+    const serverValue = resolveContentValue(serverEntry[col]);
+    if (serverValue !== null) {
+      await writeFile(filePath, serverValue, 'utf8');
+      try {
+        await setFileTimestamps(filePath, serverEntry._CreatedOn, serverEntry._LastUpdated, serverTz);
+      } catch { /* non-critical */ }
+    }
+  }
+
+  // Merge non-system, non-companion server columns into localMeta
+  const skipMeta = new Set(['_entity', '_companionReferenceColumns', '_contentColumns', '_mediaFile',
+    '_pathConfirmed', 'children', '_id']);
+  for (const [col, rawVal] of Object.entries(serverEntry)) {
+    if (skipMeta.has(col)) continue;
+    if (companions.has(col)) continue; // companion already handled as a file
+    const decoded = resolveContentValue(rawVal);
+    localMeta[col] = decoded !== null ? decoded : rawVal;
+  }
+
+  await writeFile(metaPath, JSON.stringify(localMeta, null, 2) + '\n');
+  try {
+    await setFileTimestamps(metaPath, serverEntry._CreatedOn, serverEntry._LastUpdated, serverTz);
+  } catch { /* non-critical */ }
+}