@dboio/cli 0.6.12 → 0.6.14

package/README.md

@@ -157,6 +157,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | `AppName` | string | App display name |
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
 | `AppModifyKey` | string | ModifyKey for locked/production apps (set by `dbo clone`, used for submission guards) |
+| `TransactionKeyPreset` | `RowUID` \| `RowID` | Row key type for auto-assembled expressions (set during `dbo init`/`dbo clone`, default `RowUID`) |
 | `ContentPlacement` | `bin` \| `path` \| `ask` | Where to place content files during clone |
 | `MediaPlacement` | `bin` \| `fullpath` \| `ask` | Where to place media files during clone |
 | `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
@@ -168,6 +169,10 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 
 These are set interactively on first clone and saved for future use. Pre-set them in `config.json` to skip the prompt entirely.
 
+#### `app.json._domain`
+
+The `_domain` field in `app.json` stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
+
 ### Legacy migration
 
 If your project uses the older `.domain`, `.username`, `.password`, `.cookies` files, `dbo init` will detect them and offer to migrate automatically.
@@ -195,17 +200,20 @@ dbo init --domain my-domain.com --username me@co.io   # with credentials
 dbo init --force                                      # overwrite existing config
 dbo init --domain my-domain.com --app myapp --clone   # init + clone an app
 dbo init --domain my-domain.com -y                    # skip all prompts
+dbo init --scaffold                                   # scaffold dirs (prompts for domain)
+dbo init --scaffold --yes                             # scaffold dirs non-interactively
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--domain <host>` | DBO instance domain |
 | `--username <user>` | DBO username (stored for login default) |
-| `--force` | Overwrite existing configuration |
+| `--force` | Overwrite existing configuration. Triggers a domain-change confirmation prompt when the new domain differs from the project reference domain |
 | `--app <shortName>` | App short name (triggers clone after init) |
 | `--clone` | Clone the app after initialization |
 | `-g, --global` | Install Claude commands globally (`~/.claude/commands/`) |
 | `--local` | Install Claude commands to project (`.claude/commands/`) |
+| `--scaffold` | Pre-create standard project directories (`App Versions`, `Automations`, `Bins`, `Data Sources`, `Documentation`, `Extensions`, `Groups`, `Integrations`, `Sites`) |
 | `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
 | `--non-interactive` | Alias for `--yes` |
 
@@ -233,10 +241,16 @@ dbo init --domain my-domain.com --app myapp --clone
 |------|-------------|
 | `<source>` | Local JSON file path (optional positional argument) |
 | `--app <name>` | App short name to fetch from server |
-| `--domain <host>` | Override domain |
+| `--domain <host>` | Override domain. Triggers a domain-change confirmation prompt when it differs from the project reference domain |
 | `-y, --yes` | Auto-accept all prompts |
 | `-v, --verbose` | Show HTTP request details |
 
+#### Domain change detection
+
+When cloning with a different domain than the project's reference domain (`app.json._domain` or `config.json.domain`), the CLI warns before proceeding. When `TransactionKeyPreset=RowID`, this escalates to a critical error because numeric IDs are not unique across domains — pushing to the wrong domain can corrupt records. In non-interactive mode (`-y`), RowUID domain changes proceed with a warning, but RowID domain changes throw a hard error.
+
+The project's reference domain is stored in `app.json._domain` (committed to git) during clone, giving the CLI a stable cross-user baseline.
+
 #### What clone does
 
 1. **Loads app JSON** — from a local file, server API, or interactive prompt
@@ -437,7 +451,6 @@ Output:
   Domain: my-domain.com
   Username: user@example.com
   User ID: 10296
-  User UID: albain3dwkofbhnd1qtd1q
   Directory: /Users/me/projects/operator
   Session: Active (expires: 2026-03-15T10:30:00.000Z)
   Cookies: /Users/me/projects/operator/.dbo/cookies.txt
@@ -446,7 +459,7 @@ Output:
   dbo: ✓ global (~/.claude/commands/dbo.md)
 ```
 
-User ID and UID are populated by `dbo login`. If they show "(not set)", run `dbo login` to fetch them.
+User ID is populated by `dbo login`. If it shows "(not set)", run `dbo login` to fetch it.
 
 Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `.dbo/config.local.json`.
 
@@ -489,6 +502,7 @@ dbo input -d 'RowUID:abc;column:content.Content@file.css' -v
 | `-C, --confirm <true\|false>` | Commit changes (default: `true`). Use `false` for validation only |
 | `--ticket <id>` | Override ticket ID (`_OverrideTicketID`) |
 | `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Row key type (`RowUID` or `RowID`) — no-op for `-d` passthrough, available for consistency |
 | `--login` | Auto-login user created by this submission |
 | `--transactional` | Use transactional processing |
 | `--json` | Output raw JSON response |
@@ -634,6 +648,7 @@ dbo input -d 'RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/co
 | `--ticket <id>` | Override ticket ID |
 | `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
 | `--multipart` | Use multipart/form-data upload (for binary files) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
 
 #### `dbo content pull`
 
@@ -945,6 +960,7 @@ The `@colors.css` reference tells push to read the content from that file. All o
 | `-C, --confirm <true\|false>` | Commit (default: `true`) |
 | `--ticket <id>` | Override ticket ID |
 | `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
 | `--meta-only` | Only push metadata, skip file content |
 | `--content-only` | Only push file content, skip metadata |
 | `-y, --yes` | Auto-accept all prompts |
@@ -1108,6 +1124,7 @@ The `@colors.css` reference tells the CLI to read the file content from `colors.
 | `-C, --confirm <true\|false>` | Commit (default: `true`) |
 | `--ticket <id>` | Override ticket ID |
 | `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Row key type (`RowUID` or `RowID`) — `add` always uses `RowID:add1` for new records regardless |
 | `-y, --yes` | Auto-accept all prompts |
 | `--json` | Output raw JSON |
 | `--jq <expr>` | Filter JSON response |
@@ -1328,6 +1345,9 @@ dbo deploy js:app --ticket abc123
 
 # Validate without deploying
 dbo deploy css:colors --confirm false
+
+# Deploy a multipart (binary) entry from manifest
+dbo deploy img:logo
 ```
 
 | Flag | Description |
@@ -1337,6 +1357,7 @@ dbo deploy css:colors --confirm false
 | `-C, --confirm <true\|false>` | Commit (default: `true`) |
 | `--ticket <id>` | Override ticket ID |
 | `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
 | `--json` | Output raw JSON |
 | `-v, --verbose` | Show HTTP request details |
 | `--domain <host>` | Override domain |

package/package.json

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

package/src/commands/add.js

@@ -19,6 +19,7 @@ export const addCommand = new Command('add')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
   .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
+  .option('--row-key <type>', 'Row key type (RowUID or RowID) — add uses RowID:add1 for new records regardless')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')

package/src/commands/clone.js

@@ -2,11 +2,12 @@ import { Command } from 'commander';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { join, basename, extname } from 'path';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge } from '../lib/diff.js';
+import { checkDomainChange } from '../lib/domain-guard.js';
 
 /**
  * Resolve a column value that may be base64-encoded.
@@ -437,6 +438,7 @@ export const cloneCommand = new Command('clone')
  */
 export async function performClone(source, options = {}) {
   const config = await loadConfig();
+  const effectiveDomain = options.domain || config.domain;
   let appJson;
 
   // Step 1: Load the app JSON
@@ -487,6 +489,15 @@ export async function performClone(source, options = {}) {
     throw new Error('Invalid app JSON: missing UID or children');
   }
 
+  // Domain change detection
+  if (effectiveDomain) {
+    const { changed, proceed } = await checkDomainChange(effectiveDomain, options);
+    if (changed && !proceed) {
+      log.info('Clone aborted: domain change denied.');
+      return;
+    }
+  }
+
   log.success(`Cloning "${appJson.Name}" (${appJson.ShortName})`);
 
   // Ensure sensitive files are gitignored
@@ -511,6 +522,28 @@ export async function performClone(source, options = {}) {
     log.warn('');
   }
 
+  // Prompt for TransactionKeyPreset if not already set
+  const existingPreset = await loadTransactionKeyPreset();
+  if (!existingPreset) {
+    if (options.yes || !process.stdin.isTTY) {
+      await saveTransactionKeyPreset('RowUID');
+      log.dim('  TransactionKeyPreset: RowUID (default)');
+    } else {
+      const inquirer = (await import('inquirer')).default;
+      const { preset } = await inquirer.prompt([{
+        type: 'list',
+        name: 'preset',
+        message: 'Which row key should the CLI use when building input expressions?',
+        choices: [
+          { name: 'RowUID (recommended — stable across domains)', value: 'RowUID' },
+          { name: 'RowID (numeric IDs)', value: 'RowID' },
+        ],
+      }]);
+      await saveTransactionKeyPreset(preset);
+      log.dim(`  TransactionKeyPreset: ${preset}`);
+    }
+  }
+
   // Step 3: Update package.json
   await updatePackageJson(appJson, config);
 
@@ -593,7 +626,7 @@ export async function performClone(source, options = {}) {
   }
 
   // Step 7: Save app.json with references
-  await saveAppJson(appJson, contentRefs, otherRefs);
+  await saveAppJson(appJson, contentRefs, otherRefs, effectiveDomain);
 
   // Step 8: Create .app.json baseline for delta tracking
   await saveBaselineFile(appJson);
@@ -1670,8 +1703,9 @@ export function guessExtensionForColumn(columnName) {
 /**
  * Save app.json to project root with @ references replacing processed entries.
  */
-async function saveAppJson(appJson, contentRefs, otherRefs) {
+async function saveAppJson(appJson, contentRefs, otherRefs, domain) {
   const output = { ...appJson };
+  if (domain) output._domain = domain;
   output.children = { ...appJson.children };
 
   // Replace content array with references

package/src/commands/content.js

@@ -7,6 +7,7 @@ import { formatResponse, formatError } from '../lib/formatter.js';
 import { saveToDisk } from '../lib/save-to-disk.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearGlobalTicket, getGlobalTicket, getRecordTicket } from '../lib/ticketing.js';
+import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { log } from '../lib/logger.js';
 
 function collect(value, previous) {
@@ -32,6 +33,7 @@ const deployCmd = new Command('deploy')
   .option('--ticket <id>', 'Override ticket ID')
   .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--multipart', 'Use multipart/form-data upload (for binary files)')
+  .option('--row-key <type>', 'Override row key type for this invocation (RowUID or RowID)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
@@ -63,12 +65,14 @@ const deployCmd = new Command('deploy')
         }
       }
 
+      const transactionKey = await resolveTransactionKey(options);
       const extraParams = { '_confirm': options.confirm };
       if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
       if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
 
       const isMultipart = options.multipart === true;
-      const dataExprs = isMultipart ? [] : [`RowUID:${uid};column:content.Content@${filepath}`];
+      const rowKeyExpr = transactionKey === 'RowID' ? `RowID:${uid}` : `RowUID:${uid}`;
+      const dataExprs = isMultipart ? [] : [`${rowKeyExpr};column:content.Content@${filepath}`];
 
       // Apply stored ticket if no --ticket flag
       if (!options.ticket) {
@@ -90,7 +94,7 @@ const deployCmd = new Command('deploy')
             }
           }
           const files = [{
-            fieldName: `RowUID:${uid};column:content.Content`,
+            fieldName: `${rowKeyExpr};column:content.Content`,
             filePath: filepath,
             fileName: filepath.split('/').pop(),
           }];

package/src/commands/deploy.js

@@ -5,6 +5,7 @@ import { buildInputBody, checkSubmitErrors } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearGlobalTicket, getGlobalTicket, getRecordTicket } from '../lib/ticketing.js';
+import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { log } from '../lib/logger.js';
 
 const MANIFEST_FILE = 'dbo.deploy.json';
@@ -16,6 +17,7 @@ export const deployCommand = new Command('deploy')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
   .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
+  .option('--row-key <type>', 'Override row key type for this invocation (RowUID or RowID)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
@@ -54,6 +56,9 @@ export const deployCommand = new Command('deploy')
         process.exit(1);
       }
 
+      // Resolve transaction key preset once before the entry loop
+      const transactionKey = await resolveTransactionKey(options);
+
       // ModifyKey guard — check once before any submissions
       const modifyKeyResult = await checkModifyKey(options);
       if (modifyKeyResult.cancel) {
@@ -103,9 +108,10 @@ export const deployCommand = new Command('deploy')
         if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
         if (activeModifyKey) extraParams['_modify_key'] = activeModifyKey;
 
+        const rowKeyExpr = transactionKey === 'RowID' ? `RowID:${uid}` : `RowUID:${uid}`;
         const dataExprs = isMultipart
-          ? [`RowUID:${uid};column:${entity}.Filename=${filename}`]
-          : [`RowUID:${uid};column:${entity}.${column}@${file}`];
+          ? [`${rowKeyExpr};column:${entity}.Filename=${filename}`]
+          : [`${rowKeyExpr};column:${entity}.${column}@${file}`];
 
         // Apply stored ticket if no --ticket flag
         if (!options.ticket) {
@@ -127,7 +133,7 @@ export const deployCommand = new Command('deploy')
               }
             }
             const files = [{
-              fieldName: `RowUID:${uid};column:${entity}.${column}`,
+              fieldName: `${rowKeyExpr};column:${entity}.${column}`,
               filePath: file,
               fileName: file.split('/').pop(),
             }];

package/src/commands/init.js

@@ -1,9 +1,11 @@
 import { Command } from 'commander';
-import { access } from 'fs/promises';
+import { access, readdir } from 'fs/promises';
 import { join } from 'path';
-import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore } from '../lib/config.js';
+import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore, saveTransactionKeyPreset } from '../lib/config.js';
 import { installOrUpdateClaudeCommands } from './install.js';
+import { scaffoldProjectDirs, logScaffoldResult } from '../lib/scaffold.js';
 import { log } from '../lib/logger.js';
+import { checkDomainChange, writeAppJsonDomain } from '../lib/domain-guard.js';
 
 export const initCommand = new Command('init')
   .description('Initialize DBO CLI configuration for the current directory')
@@ -16,11 +18,17 @@ export const initCommand = new Command('init')
   .option('--non-interactive', 'Skip all interactive prompts')
   .option('-g, --global', 'Install Claude commands to user home directory (~/.claude/commands/)')
   .option('--local', 'Install Claude commands to project directory (.claude/commands/)')
+  .option('--scaffold', 'Create standard project directories (App Versions, Automations, Bins, …)')
   .action(async (options) => {
     // Merge --yes into nonInteractive
     if (options.yes) options.nonInteractive = true;
     try {
       if (await isInitialized() && !options.force) {
+        if (options.scaffold) {
+          const result = await scaffoldProjectDirs();
+          logScaffoldResult(result);
+          return;
+        }
         log.warn('Already initialized. Use --force to overwrite.');
         return;
       }
@@ -49,24 +57,79 @@ export const initCommand = new Command('init')
       if (!domain || !username) {
         const inquirer = (await import('inquirer')).default;
         const answers = await inquirer.prompt([
-          { type: 'input', name: 'domain', message: 'Domain (e.g., myapp.dbo.io):', default: domain || undefined, when: !domain, validate: v => v ? true : 'Domain is required' },
+          { type: 'input', name: 'domain', message: 'Domain (e.g., myapp.dbo.io):', default: domain || undefined, when: !domain },
           { type: 'input', name: 'username', message: 'Username (email):', when: !username },
         ]);
         domain = domain || answers.domain;
         username = username || answers.username;
       }
 
+      let domainChanged = false;
+      if (options.force) {
+        const { changed, proceed } = await checkDomainChange(domain, options);
+        if (changed && !proceed) {
+          log.info('Init aborted: domain change denied.');
+          return;
+        }
+        domainChanged = changed;
+      }
+
       await initConfig(domain);
       if (username) {
         await saveCredentials(username);
       }
 
+      if (options.force && domainChanged) {
+        await writeAppJsonDomain(domain);
+      }
+
       // Ensure sensitive files are gitignored
       await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt', '.dbo/config.local.json', '.dbo/ticketing.local.json']);
 
       log.success(`Initialized .dbo/ for ${domain}`);
       log.dim('  Run "dbo login" to authenticate.');
 
+      // Prompt for TransactionKeyPreset
+      if (!options.nonInteractive) {
+        const inquirer = (await import('inquirer')).default;
+        const { preset } = await inquirer.prompt([{
+          type: 'list',
+          name: 'preset',
+          message: 'Which row key should the CLI use when building input expressions?',
+          choices: [
+            { name: 'RowUID (recommended — stable across domains)', value: 'RowUID' },
+            { name: 'RowID (numeric IDs)', value: 'RowID' },
+          ],
+        }]);
+        await saveTransactionKeyPreset(preset);
+        log.dim(`  TransactionKeyPreset: ${preset}`);
+      } else {
+        await saveTransactionKeyPreset('RowUID');
+      }
+
+      // ─── Scaffold ─────────────────────────────────────────────────────────────
+      let shouldScaffold = options.scaffold;
+
+      if (!shouldScaffold && !options.nonInteractive) {
+        const entries = await readdir(process.cwd());
+        const IGNORED = new Set(['.dbo', '.claude', '.idea', '.vscode']);
+        const isEmpty = entries.every(e => IGNORED.has(e));
+
+        const inquirer = (await import('inquirer')).default;
+        const { doScaffold } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'doScaffold',
+          message: 'Would you like to scaffold the standard project directory structure?',
+          default: isEmpty,
+        }]);
+        shouldScaffold = doScaffold;
+      }
+
+      if (shouldScaffold) {
+        const result = await scaffoldProjectDirs();
+        logScaffoldResult(result);
+      }
+
       // Clone if requested
       if (options.clone || options.app) {
         let appShortName = options.app;

package/src/commands/input.js

@@ -18,6 +18,7 @@ export const inputCommand = new Command('input')
   .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')
   .option('--login', 'Auto-login user created by this submission')
   .option('--transactional', 'Use transactional processing')
   .option('--json', 'Output raw JSON response')

package/src/commands/push.js

@@ -9,6 +9,7 @@ import { shouldSkipColumn } from '../lib/columns.js';
 import { loadConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.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 } from '../lib/timestamps.js';
 import { findMetadataFiles } from '../lib/diff.js';
 import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
@@ -23,6 +24,7 @@ export const pushCommand = new Command('push')
   .option('--meta-only', 'Only push metadata changes, skip file content')
   .option('--content-only', 'Only push file content, skip metadata columns')
   .option('-y, --yes', 'Auto-accept all prompts (path refactoring, etc.)')
+  .option('--row-key <type>', 'Override row key type for this invocation (RowUID or RowID)')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')
   .option('-v, --verbose', 'Show HTTP request details')
@@ -39,15 +41,18 @@ export const pushCommand = new Command('push')
       }
       const modifyKey = modifyKeyResult.modifyKey;
 
+      // Resolve transaction key preset
+      const transactionKey = await resolveTransactionKey(options);
+
       // Process pending deletions from synchronize.json
-      await processPendingDeletes(client, options, modifyKey);
+      await processPendingDeletes(client, options, modifyKey, transactionKey);
 
       const pathStat = await stat(targetPath);
 
       if (pathStat.isDirectory()) {
-        await pushDirectory(targetPath, client, options, modifyKey);
+        await pushDirectory(targetPath, client, options, modifyKey, transactionKey);
       } else {
-        await pushSingleFile(targetPath, client, options, modifyKey);
+        await pushSingleFile(targetPath, client, options, modifyKey, transactionKey);
       }
     } catch (err) {
       formatError(err);
@@ -58,7 +63,7 @@ export const pushCommand = new Command('push')
 /**
  * Process pending delete entries from .dbo/synchronize.json
  */
-async function processPendingDeletes(client, options, modifyKey = null) {
+async function processPendingDeletes(client, options, modifyKey = null, transactionKey = 'RowUID') {
   const sync = await loadSynchronize();
   if (!sync.delete || sync.delete.length === 0) return;
 
@@ -140,7 +145,7 @@ async function processPendingDeletes(client, options, modifyKey = null) {
 /**
  * Push a single file using its companion .metadata.json
  */
-async function pushSingleFile(filePath, client, options, modifyKey = null) {
+async function pushSingleFile(filePath, client, options, modifyKey = null, transactionKey = 'RowUID') {
   // Find the metadata file
   const dir = dirname(filePath);
   const base = basename(filePath, extname(filePath));
@@ -154,13 +159,13 @@ async function pushSingleFile(filePath, client, options, modifyKey = null) {
     process.exit(1);
   }
 
-  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey);
+  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
 }
 
 /**
  * Push all records found in a directory (recursive)
  */
-async function pushDirectory(dirPath, client, options, modifyKey = null) {
+async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID') {
   const metaFiles = await findMetadataFiles(dirPath);
 
   if (metaFiles.length === 0) {
@@ -272,7 +277,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null) {
 
   for (const item of toPush) {
     try {
-      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey);
+      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey, transactionKey);
       if (success) {
         succeeded++;
         successfulPushes.push(item);
@@ -306,14 +311,37 @@ async function pushDirectory(dirPath, client, options, modifyKey = null) {
  * @param {string[]|null} changedColumns - Optional array of changed column names (for delta sync)
  * @returns {Promise<boolean>} - True if push succeeded
  */
-async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null, modifyKey = null) {
-  const uid = meta.UID || meta._id;
+async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null, modifyKey = null, transactionKey = 'RowUID') {
+  const uid = meta.UID;
+  const id = meta._id;
   const entity = meta._entity;
   const contentCols = new Set(meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
-  if (!uid) {
-    throw new Error(`No UID found in ${metaPath}`);
+  // Determine the row key prefix and value based on the preset
+  let rowKeyPrefix, rowKeyValue;
+  if (transactionKey === 'RowID') {
+    if (id) {
+      rowKeyPrefix = 'RowID';
+      rowKeyValue = id;
+    } else {
+      log.warn(`  ⚠  Preset is RowID but no _id found in ${basename(metaPath)} — falling back to RowUID`);
+      rowKeyPrefix = 'RowUID';
+      rowKeyValue = uid;
+    }
+  } else {
+    if (uid) {
+      rowKeyPrefix = 'RowUID';
+      rowKeyValue = uid;
+    } else if (id) {
+      log.warn(`  ⚠  Preset is RowUID but no UID found in ${basename(metaPath)} — falling back to RowID`);
+      rowKeyPrefix = 'RowID';
+      rowKeyValue = id;
+    }
+  }
+
+  if (!rowKeyValue) {
+    throw new Error(`No UID or _id found in ${metaPath}`);
   }
   if (!entity) {
     throw new Error(`No _entity found in ${metaPath}`);
@@ -351,9 +379,9 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
       // @filename reference — resolve to actual file path
       const refFile = strValue.substring(1);
       const refPath = join(metaDir, refFile);
-      dataExprs.push(`RowUID:${uid};column:${entity}.${key}@${refPath}`);
+      dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${key}@${refPath}`);
     } else {
-      dataExprs.push(`RowUID:${uid};column:${entity}.${key}=${strValue}`);
+      dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${key}=${strValue}`);
     }
   }
 
@@ -363,10 +391,10 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   }
 
   const fieldLabel = changedColumns ? `${dataExprs.length} changed field(s)` : `${dataExprs.length} field(s)`;
-  log.info(`Pushing ${basename(metaPath, '.metadata.json')} (${entity}:${uid}) — ${fieldLabel}`);
+  log.info(`Pushing ${basename(metaPath, '.metadata.json')} (${entity}:${rowKeyValue}) — ${fieldLabel}`);
 
   // Apply stored ticket if no --ticket flag
-  await applyStoredTicketToSubmission(dataExprs, entity, uid, uid, options);
+  await applyStoredTicketToSubmission(dataExprs, entity, uid || id, uid || id, options);
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
@@ -422,7 +450,7 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   }
 
   // Clean up per-record ticket on success
-  await clearRecordTicket(uid);
+  await clearRecordTicket(uid || id);
 
   // Update file timestamps from server response
   try {

package/src/commands/status.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { loadConfig, isInitialized, getActiveCookiesPath, loadUserInfo, getAllPluginScopes } from '../lib/config.js';
+import { loadConfig, isInitialized, getActiveCookiesPath, loadUserInfo, getAllPluginScopes, loadTransactionKeyPreset } from '../lib/config.js';
 import { loadCookies } from '../lib/cookie-jar.js';
 import { access } from 'fs/promises';
 import { join } from 'path';
@@ -18,7 +18,6 @@ export const statusCommand = new Command('status')
       log.label('Username', config.username || '(not set)');
       const userInfo = await loadUserInfo();
       log.label('User ID', userInfo.userId || '(not set)');
-      log.label('User UID', userInfo.userUid || '(not set — run "dbo login")');
       log.label('Directory', process.cwd());
 
       const cookiesPath = await getActiveCookiesPath();
@@ -38,6 +37,9 @@ export const statusCommand = new Command('status')
         log.label('Session', 'No active session. Run "dbo login".');
       }
 
+      const transactionKeyPreset = await loadTransactionKeyPreset();
+      log.label('Transaction Key', transactionKeyPreset || '(not set — defaults to RowUID)');
+
       // Display plugin status
       const scopes = await getAllPluginScopes();
       const pluginNames = Object.keys(scopes);

package/src/lib/config.js

@@ -555,6 +555,31 @@ export async function loadAppModifyKey() {
   } catch { return null; }
 }
 
+// ─── TransactionKeyPreset ─────────────────────────────────────────────────
+
+/**
+ * Save TransactionKeyPreset to .dbo/config.json.
+ * @param {'RowUID'|'RowID'} preset
+ */
+export async function saveTransactionKeyPreset(preset) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  existing.TransactionKeyPreset = preset;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load TransactionKeyPreset from .dbo/config.json.
+ * Returns 'RowUID', 'RowID', or null if not set.
+ */
+export async function loadTransactionKeyPreset() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    return JSON.parse(raw).TransactionKeyPreset || null;
+  } catch { return null; }
+}
+
 // ─── Gitignore ────────────────────────────────────────────────────────────
 
 /**

package/src/lib/domain-guard.js

@@ -0,0 +1,95 @@
+import { readFile, writeFile, stat, utimes } from 'fs/promises';
+import { join } from 'path';
+import { loadConfig, loadTransactionKeyPreset } from './config.js';
+import { log } from './logger.js';
+
+const appJsonPath = () => join(process.cwd(), 'app.json');
+
+/** Read _domain from app.json. Returns null if file missing or field absent. */
+export async function readAppJsonDomain() {
+  try {
+    const obj = JSON.parse(await readFile(appJsonPath(), 'utf8'));
+    return obj._domain || null;
+  } catch { return null; }
+}
+
+/**
+ * Write _domain to app.json, preserving mtime so git doesn't see a spurious change.
+ * No-op if app.json does not exist.
+ */
+export async function writeAppJsonDomain(domain) {
+  const path = appJsonPath();
+  let originalStat;
+  try { originalStat = await stat(path); } catch { return; }
+  const obj = JSON.parse(await readFile(path, 'utf8'));
+  obj._domain = domain;
+  await writeFile(path, JSON.stringify(obj, null, 2) + '\n');
+  await utimes(path, originalStat.atime, originalStat.mtime); // restore mtime
+}
+
+/**
+ * Check whether newDomain differs from the project reference domain.
+ * Reference = app.json._domain (authoritative) → fallback: config.json.domain.
+ * If reference is absent entirely, returns { changed: false } (no warning).
+ *
+ * Returns { changed: false } or { changed: true, proceed: bool }.
+ * Throws in non-interactive mode when TransactionKeyPreset=RowID and domain changes.
+ */
+export async function checkDomainChange(newDomain, options = {}) {
+  let referenceDomain = await readAppJsonDomain();
+  if (!referenceDomain) {
+    const config = await loadConfig();
+    referenceDomain = config.domain || null;
+  }
+  if (!referenceDomain) return { changed: false };
+
+  const norm = d => d ? String(d).replace(/^https?:\/\//, '').replace(/\/$/, '').toLowerCase() : null;
+  if (norm(newDomain) === norm(referenceDomain)) return { changed: false };
+
+  const preset = await loadTransactionKeyPreset();
+  const isRowID = preset === 'RowID';
+
+  if (options.yes || !process.stdin.isTTY) {
+    if (isRowID) {
+      throw new Error(
+        `Domain change detected: "${referenceDomain}" → "${newDomain}"\n` +
+        `Cannot proceed in non-interactive mode with TransactionKeyPreset=RowID. ` +
+        `Numeric IDs are not unique across domains — submitting to the wrong domain may overwrite or corrupt records.`
+      );
+    }
+    log.warn(`Domain change detected: "${referenceDomain}" → "${newDomain}". Proceeding (TransactionKeyPreset=RowUID).`);
+    return { changed: true, proceed: true };
+  }
+
+  const inquirer = (await import('inquirer')).default;
+  log.plain('');
+
+  if (isRowID) {
+    log.error('⛔  CRITICAL: Domain change detected');
+    log.warn(`  Reference domain : ${referenceDomain}`);
+    log.warn(`  New domain       : ${newDomain}`);
+    log.plain('');
+    log.warn('  TransactionKeyPreset=RowID is active. Numeric IDs are NOT unique across');
+    log.warn('  domains. Pushing to the wrong domain may overwrite or corrupt records in');
+    log.warn('  a different app.');
+    log.plain('');
+    const { confirmText } = await inquirer.prompt([{
+      type: 'input',
+      name: 'confirmText',
+      message: `Type "yes, change domain" to confirm switching to "${newDomain}":`,
+    }]);
+    return { changed: true, proceed: confirmText.trim() === 'yes, change domain' };
+  }
+
+  log.warn('⚠  Domain change detected');
+  log.dim(`  Reference domain : ${referenceDomain}`);
+  log.dim(`  New domain       : ${newDomain}`);
+  log.plain('');
+  const { confirm } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'confirm',
+    message: `Switch domain from "${referenceDomain}" to "${newDomain}"?`,
+    default: false,
+  }]);
+  return { changed: true, proceed: confirm };
+}

package/src/lib/scaffold.js

@@ -0,0 +1,62 @@
+import { mkdir, stat, writeFile, access } from 'fs/promises';
+import { join } from 'path';
+import { DEFAULT_PROJECT_DIRS } from './structure.js';
+import { log } from './logger.js';
+
+/**
+ * Scaffold the standard DBO project directory structure in cwd.
+ * Creates missing directories, skips existing ones, warns on name conflicts.
+ * Also creates app.json with {} if absent.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<{ created: string[], skipped: string[], warned: string[] }>}
+ */
+export async function scaffoldProjectDirs(cwd = process.cwd()) {
+  const created = [];
+  const skipped = [];
+  const warned  = [];
+
+  for (const dir of DEFAULT_PROJECT_DIRS) {
+    const target = join(cwd, dir);
+    try {
+      const s = await stat(target);
+      if (s.isDirectory()) {
+        skipped.push(dir);
+      } else {
+        log.warn(`  Skipping "${dir}" — a file with that name already exists`);
+        warned.push(dir);
+      }
+    } catch {
+      // Does not exist — create it
+      await mkdir(target, { recursive: true });
+      created.push(dir);
+    }
+  }
+
+  // Create app.json if absent
+  const appJsonPath = join(cwd, 'app.json');
+  try {
+    await access(appJsonPath);
+  } catch {
+    await writeFile(appJsonPath, '{}\n');
+    created.push('app.json');
+  }
+
+  return { created, skipped, warned };
+}
+
+/**
+ * Print the scaffold summary to the console.
+ * @param {{ created: string[], skipped: string[], warned: string[] }} result
+ */
+export function logScaffoldResult({ created, skipped, warned }) {
+  if (created.length) {
+    log.success('Scaffolded directories:');
+    for (const d of created) log.dim(`  + ${d}`);
+  }
+  if (skipped.length) {
+    log.dim('Skipped (already exist):');
+    for (const d of skipped) log.dim(`  · ${d}`);
+  }
+  // warned items already printed inline during scaffold
+}

package/src/lib/transaction-key.js

@@ -0,0 +1,46 @@
+import { loadTransactionKeyPreset, saveTransactionKeyPreset } from './config.js';
+import { log } from './logger.js';
+
+/**
+ * Resolve the active transaction key preset.
+ * Priority: --row-key flag > config > lazy prompt > default RowUID.
+ *
+ * @param {Object} options - Command options (may have .rowKey)
+ * @returns {Promise<'RowUID'|'RowID'>}
+ */
+export async function resolveTransactionKey(options = {}) {
+  // 1. --row-key flag takes precedence (no config write)
+  if (options.rowKey) return options.rowKey;
+
+  // 2. Check config
+  const stored = await loadTransactionKeyPreset();
+  if (stored) return stored;
+
+  // 3. Non-interactive or -y: default to RowUID, save to config
+  if (options.yes || options.nonInteractive || !process.stdin.isTTY) {
+    await saveTransactionKeyPreset('RowUID');
+    return 'RowUID';
+  }
+
+  // 4. Lazy prompt (first submission without preset configured)
+  log.plain('');
+  log.info('TransactionKeyPreset is not configured.');
+  log.dim('  RowUID — stable across domains (recommended)');
+  log.dim('  RowID  — uses numeric IDs (may differ across domains)');
+  log.plain('');
+
+  const inquirer = (await import('inquirer')).default;
+  const { preset } = await inquirer.prompt([{
+    type: 'list',
+    name: 'preset',
+    message: 'Which row key should the CLI use when building input expressions?',
+    choices: [
+      { name: 'RowUID (recommended — stable across domains)', value: 'RowUID' },
+      { name: 'RowID (numeric IDs)', value: 'RowID' },
+    ],
+  }]);
+
+  await saveTransactionKeyPreset(preset);
+  log.dim(`  Saved TransactionKeyPreset: ${preset} to .dbo/config.json`);
+  return preset;
+}