@dboio/cli 0.8.2 → 0.9.3

package/README.md

@@ -116,6 +116,39 @@ dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
 
 ---
 
+## Project Directory Structure
+
+When you run `dbo init --scaffold` or `dbo clone`, the following standard directories are created in your project root:
+
+```
+my-project/
+├── .dbo/               # Config, synchronization and session info for dbo cli commands
+├── .claude/            # Claude Code plugin config (commands, specs, plans, skills)
+├── node_modules/       # Automatically created; contains all external libraries
+├── src/                # Your actual source code (sass, typescript, etc.)
+├── tests/              # Project-level tests
+├── bins/               # Assets (contents, outputs, images, HTML, CSS)
+├── trash/              # Staged soft-deleted files from dbo rm
+├── automation/         # Automation entity records
+├── app_version/        # App version entity records
+├── data_source/        # Data source entity records
+├── docs/               # Project documentation and docs entities
+├── extension/          # Extension entity records
+│   ├── <DescriptorType>/   # Sub-directory per descriptor type (e.g., component/, form/)
+│   └── _unsupported/       # Extensions with unrecognized descriptor types
+├── group/              # Group entity records
+├── integration/        # Integration entity records
+├── site/               # Site entity records
+├── .gitignore          # Tells Git to ignore files in the repo sync
+├── .dboignore          # Tells dbo cli to ignore files in commands
+├── package.json        # Metadata, scripts, and dependency list
+└── package-lock.json   # Records exact versions of dependencies installed
+```
+
+> **Breaking change from pre-0.9.1**: Directory names have changed from mixed-case (`Extensions/`, `App Versions/`, `bins/`) to lowercase snake_case (`extension/`, `app_version/`, `bins/`). If you have an existing project, rename your directories manually before running `dbo clone` again.
+
+---
+
 ## Configuration
 
 All configuration is **directory-scoped**. Each project folder maintains its own `.dbo/` directory with its own domain and session. Switch environments by switching directories:
@@ -135,6 +168,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | `credentials.json` | Username, user ID, UID, name, email (no password) | Gitignored (per-user) |
 | `cookies.txt` | Session cookie (Netscape format) | Gitignored (per-user) |
 | `structure.json` | Bin directory mapping (created by `dbo clone`) | Committable (shared) |
+| `metadata_templates.json` | Column templates per entity/descriptor (auto-generated by `dbo clone`) | Committable (shared) |
 
 `dbo init` automatically adds `.dbo/credentials.json`, `.dbo/cookies.txt`, `.dbo/config.local.json`, and `.dbo/ticketing.local.json` to `.gitignore` (creates the file if it doesn't exist).
 
@@ -197,13 +231,13 @@ A gitignore-style file in the project root that controls which files and directo
 **/*.CustomSQL.sql
 
 # Ignore a specific record (by metadata file path)
-Bins/app/my-draft-page.metadata.json
+bins/app/my-draft-page.metadata.json
 
 # Ignore an entire directory
-Bins/staging/
+bins/staging/
 
-# Ignore all content in Bins/ (still push entity-dir records like Extensions/)
-Bins/
+# Ignore all content in bins/ (still push entity-dir records like extension/)
+bins/
 ```
 
 **Syntax:** Same as `.gitignore` — glob patterns, `#` comments, blank lines, negation with `!`, directory-only patterns with trailing `/`.
@@ -272,8 +306,9 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `--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`) |
+| `--scaffold` | Pre-create standard project directories (`app_version`, `automation`, `bins`, `data_source`, `docs`, `extension`, `group`, `integration`, `site`, `src`, `tests`, `trash`) |
 | `--dboignore` | Create `.dboignore` with default patterns (use with `--force` to overwrite existing) |
+| `--media-placement <placement>` | Set media placement when cloning: `fullpath` or `binpath` (default: `bin`) |
 | `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
 | `--non-interactive` | Alias for `--yes` |
 
@@ -309,7 +344,8 @@ dbo clone -e extension --descriptor-types false   # Clone extensions flat (no de
 | `--app <name>` | App short name to fetch from server |
 | `-e, --entity <type>` | Only clone a specific entity type (e.g. `output`, `content`, `media`, `extension`) |
 | `--documentation-only` | When used with `-e extension`, clone only documentation extensions |
-| `--descriptor-types <bool>` | Sort extensions into descriptor sub-directories (default: `true`). Set to `false` to use flat `Extensions/` layout |
+| `--descriptor-types <bool>` | Sort extensions into descriptor sub-directories (default: `true`). Set to `false` to use flat `extension/` layout |
+| `--media-placement <placement>` | Set media placement: `fullpath` or `binpath` (default: `bin`). Skips interactive media placement prompt |
 | `--domain <host>` | Override domain. Triggers a domain-change confirmation prompt when it differs from the project reference domain |
 | `--force` | Skip source mismatch confirmation and change detection; re-processes all files |
 | `-y, --yes` | Auto-accept all prompts (also skips source mismatch confirmation) |
@@ -330,7 +366,7 @@ The project's reference domain is stored in `app.json._domain` (committed to git
 5. **Saves `.dbo/structure.json`** — maps BinIDs to directory paths for file placement
 6. **Writes content files** — decodes base64 content, creates `*.metadata.json` + content files in the correct bin directory. When a record's `Extension` field is empty, prompts you to choose from `css`, `js`, `html`, `xml`, `txt`, `md`, `cs`, `json`, `sql` (or skip to keep no extension). The chosen extension is saved back into the `metadata.json` `Extension` field
 7. **Downloads media files** — fetches binary files (images, CSS, fonts) from the server via `/api/media/{uid}` and saves with metadata
-8. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory (e.g., `Extensions/`, `Data Sources/`)
+8. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory (e.g., `extension/`, `data_source/`)
 9. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
 10. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
 
@@ -367,7 +403,7 @@ When cloning an app that was already cloned locally, the CLI detects existing fi
 When multiple records would create files at the same path (e.g., a `content` record and a `media` record both named `colors.css`), the CLI detects the collision before writing any files and prompts you to choose which record to keep:
 
 ```
-⚠ Collision: 2 records want to create "Bins/app/colors.css"
+⚠ Collision: 2 records want to create "bins/app/colors.css"
 ? Which record should create this file?
 ❯ [content] colors (UID: abc123)
   [media] colors.css (UID: def456)
@@ -405,13 +441,13 @@ Entity types that correspond to project directories (`extension`, `app_version`,
 
 | Entity Key | Directory |
 |------------|-----------|
-| `extension` | `Extensions/<Descriptor>/` (see below) |
-| `app_version` | `App Versions/` |
-| `data_source` | `Data Sources/` |
-| `site` | `Sites/` |
-| `group` | `Groups/` |
-| `integration` | `Integrations/` |
-| `automation` | `Automations/` |
+| `extension` | `extension/<Descriptor>/` (see below) |
+| `app_version` | `app_version/` |
+| `data_source` | `data_source/` |
+| `site` | `site/` |
+| `group` | `group/` |
+| `integration` | `integration/` |
+| `automation` | `automation/` |
 
 For each entity type, the CLI prompts to choose which column becomes the filename (defaults to `Name`, fallback `UID`). The choice is saved per entity type in `config.json` (e.g., `ExtensionFilenameCol`).
 
@@ -421,13 +457,13 @@ Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
 #### Extension descriptor sub-directories
 
-Extension records are organized into sub-directories under `Extensions/` based on their `Descriptor` column value. A special extension type called `descriptor_definition` (itself an extension with `Descriptor === "descriptor_definition"`) provides the mapping from descriptor key (`String1`) to display/directory name (`Name`).
+Extension records are organized into sub-directories under `extension/` based on their `Descriptor` column value. A special extension type called `descriptor_definition` (itself an extension with `Descriptor === "descriptor_definition"`) provides the mapping from descriptor key (`String1`) to display/directory name (`Name`).
 
 During clone, the CLI:
 
 1. **Pre-scans** all extension records for `descriptor_definition` entries and builds a `String1 → Name` mapping
-2. **Creates sub-directories** under `Extensions/` for each mapped descriptor (e.g., `Extensions/Documentation/`, `Extensions/Includes/`)
-3. **Always creates** `Extensions/Unsupported/` — extensions with an unmapped or null `Descriptor` are placed here
+2. **Creates sub-directories** under `extension/` for each mapped descriptor (e.g., `extension/Documentation/`, `extension/Includes/`)
+3. **Always creates** `extension/_unsupported/` — extensions with an unmapped or null `Descriptor` are placed here
 4. **Prompts per descriptor** — filename column and content extraction prompts fire once per unique `Descriptor` value (not once for all extensions)
 5. **Persists the mapping** in `.dbo/structure.json` under `descriptorMapping`
 
@@ -441,10 +477,10 @@ During clone, the CLI:
 
 **Documentation alternate placement**: When extracting MD content from `documentation` descriptor extensions, the CLI offers a choice:
 
-- **Root placement** (`/Documentation/<filename>.md`) — recommended for easy access; creates `@/Documentation/<filename>.md` references in metadata
-- **Inline placement** (`Extensions/Documentation/<filename>.md`) — keeps files alongside metadata
+- **Root placement** (`/docs/<filename>.md`) — recommended for easy access; creates `@/docs/<filename>.md` references in metadata
+- **Inline placement** (`extension/Documentation/<filename>.md`) — keeps files alongside metadata
 
-Root-placed files use absolute-from-root `@/` references (e.g., `@/Documentation/my-doc.md`) so `dbo push` can locate them regardless of where the metadata lives.
+Root-placed files use absolute-from-root `@/` references (e.g., `@/docs/my-doc.md`) so `dbo push` can locate them regardless of where the metadata lives.
 
 **Entity filter support**:
 
@@ -455,7 +491,7 @@ dbo clone -e extension                               # Clone all extensions (all
 dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
 ```
 
-**`dbo add` auto-inference**: Running `dbo add Documentation/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `Extensions/Documentation/` with the correct `@/` reference.
+**`dbo add` auto-inference**: Running `dbo add docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `extension/documentation/` with the correct `@/` reference.
 
 #### Output structure
 
@@ -467,7 +503,7 @@ project/
   .gitignore                 # credentials.json + cookies.txt added
   package.json               # Updated with app info + deploy script
   app.json                   # Clone of original with @references
-  Bins/                      # ← root for all bin-placed files
+  bins/                      # ← root for all bin-placed files
     app/                     # ← directory from children.bin
       thomas-scratch.md
       thomas-scratch.metadata.json
@@ -475,67 +511,93 @@ project/
       CurrentTicketID.metadata.json
     ticket_test/             # ← another bin directory
       ...
-  Extensions/                # ← extension records organized by descriptor
+  extension/                 # ← extension records organized by descriptor
     Documentation/           # ← descriptor sub-directory (from descriptor_definition)
       MyDoc.uid1.metadata.json
       MyDoc.uid1.String10.md     # ← extracted content column
     Includes/
       Header.uid2.metadata.json
-    Unsupported/             # ← always created (unmapped/null descriptors)
-  Documentation/             # ← root-placed documentation MD files (optional)
+    _unsupported/            # ← always created (unmapped/null descriptors)
+  docs/                      # ← root-placed documentation MD files (optional)
     MyDoc.md
-  Data Sources/
+  data_source/
     MySQL-Primary.metadata.json
-  Sites/
+  site/
     MainSite.metadata.json
   media/operator/app/...     # ← FullPath placement (when MediaPlacement=fullpath)
 ```
 
-#### Understanding the `Bins/` directory structure
+#### Understanding the `bins/` directory structure
 
-The `Bins/` directory is the default location for all bin-placed content files during clone. It organizes files according to your app's bin hierarchy from DBO.io.
+The `bins/` directory is the default location for all bin-placed content files during clone. It organizes files according to your app's bin hierarchy from DBO.io.
 
 **Directory Organization:**
 
-- **`Bins/`** — Root directory for all bin-placed files (local organizational directory only)
-  - **`Bins/app/`** — Special subdirectory for the main app bin (typically the default bin)
-  - **`Bins/custom_name/`** — Custom bin directories (e.g., `tpl/`, `ticket_test/`, etc.)
+- **`bins/`** — Root directory for all bin-placed files (local organizational directory only)
+  - **`bins/app/`** — Special subdirectory for the main app bin (typically the default bin)
+  - **`bins/custom_name/`** — Custom bin directories (e.g., `tpl/`, `ticket_test/`, etc.)
 
-**Important: The `Bins/app/` special case**
+**Important: The `bins/app/` special case**
 
-The `app/` subdirectory under `Bins/` is treated specially:
+The `app/` subdirectory under `bins/` is treated specially:
 
-1. **It's organizational only** — The `Bins/app/` prefix exists only for local file organization and is **not part of the server-side path**.
+1. **It's organizational only** — The `bins/app/` prefix exists only for local file organization and is **not part of the server-side path**.
 
-2. **Path normalization** — When comparing paths (during `dbo push`), the CLI automatically strips both `Bins/` and `app/` from paths:
+2. **Path normalization** — When comparing paths (during `dbo push`), the CLI automatically strips both `bins/` and `app/` from paths:
    ```
-   Local file:    Bins/app/assets/css/operator.css
+   Local file:    bins/app/assets/css/operator.css
    Server Path:   assets/css/operator.css
    → These are considered the same path ✓
    ```
 
-3. **Custom bins are preserved** — Other subdirectories like `Bins/tpl/` or `Bins/ticket_test/` represent actual bin hierarchies and their names are meaningful:
+3. **Custom bins are preserved** — Other subdirectories like `bins/tpl/` or `bins/ticket_test/` represent actual bin hierarchies and their names are meaningful:
    ```
-   Local file:    Bins/tpl/header.html
+   Local file:    bins/tpl/header.html
    Server Path:   tpl/header.html
    → The 'tpl/' directory is preserved ✓
    ```
 
 **Why this matters:**
 
-- When you `dbo push` files from `Bins/app/`, the CLI knows these paths should match the root-level paths in your metadata
-- If your metadata `Path` column contains `assets/css/colors.css`, it will correctly match files in `Bins/app/assets/css/colors.css`
-- Custom bin directories like `Bins/tpl/` serve from the `tpl/` directive and maintain their path structure
+- When you `dbo push` files from `bins/app/`, the CLI knows these paths should match the root-level paths in your metadata
+- If your metadata `Path` column contains `assets/css/colors.css`, it will correctly match files in `bins/app/assets/css/colors.css`
+- Custom bin directories like `bins/tpl/` serve from the `tpl/` directive and maintain their path structure
 
 **Leading slash handling:**
 
 The CLI handles leading `/` in metadata paths flexibly:
-- `Path: assets/css/file.css` matches `Bins/app/assets/css/file.css` ✓
-- `Path: /assets/css/file.css` also matches `Bins/app/assets/css/file.css` ✓
-- `Path: /assets/css/file.css` matches `Bins/assets/css/file.css` ✓
+- `Path: assets/css/file.css` matches `bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` also matches `bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` matches `bins/assets/css/file.css` ✓
 
 This ensures compatibility with various path formats from the server while maintaining correct local file organization.
 
+#### Metadata Templates
+
+During `dbo clone`, the CLI auto-generates `.dbo/metadata_templates.json` — a file that records which columns each entity/descriptor uses. This file is seeded from the first cloned record of each type and can be manually edited afterwards.
+
+**File format:**
+
+```json
+{
+  "site": ["AppID", "Name", "ShortName", "Active"],
+  "extension": {
+    "documentation": ["AppID", "Name", "Descriptor=documentation", "String10=@reference"],
+    "control": ["AppID", "Name", "ShortName", "Active"]
+  }
+}
+```
+
+**Column syntax:**
+
+| Syntax | Meaning |
+|--------|---------|
+| `Name` | Plain column — populated from filename or left empty |
+| `Descriptor=documentation` | Literal value — always set to `documentation` |
+| `String10=@reference` | Content reference — links to the file being added |
+
+`dbo add` uses these templates to auto-detect the entity type from a file's directory placement and generate metadata without prompting. For example, `dbo add extension/include/nav.html` resolves to entity `extension` / descriptor `include` and applies the matching template.
+
 ---
 
 ### `dbo login`
@@ -747,8 +809,20 @@ The save-to-disk feature fetches data and persists records as local files. It us
 4. **Extension** — use an entity column or specify manually
 
 Each record produces:
-- A content file: `[filename].[extension]`
-- A metadata file: `[filename].metadata.json` (all column values)
+- A content file: `[filename]~[uid].[extension]` (e.g., `colors~abc123.css`)
+- A metadata file: `[filename]~[uid].metadata.json` (all column values)
+
+### Tilde UID Convention
+
+Every local file whose server record has a known UID embeds that UID in the filename, separated by a tilde (`~`):
+
+- Content: `<basename>~<uid>.<ext>` / `<basename>~<uid>.metadata.json`
+- Media: `<basename>~<uid>.<ext>` / `<basename>~<uid>.<ext>.metadata.json`
+- Entity-dir: `<name>~<uid>.metadata.json`
+
+Exception: if the chosen filename column value *is* the UID itself, the tilde suffix is omitted: `<uid>.<ext>`.
+
+When pushing, the `~<uid>` portion is automatically stripped from filenames sent to the server (e.g., `logo~def456.png` is uploaded as `logo.png`).
 
 If the path column contains a filename (e.g., `assets/js/main.js`), the CLI detects it and asks if you want to use it.
 
@@ -1133,29 +1207,29 @@ Remove a file or directory locally and stage server deletions for the next `dbo
 
 ```bash
 # Remove a content file (finds companion .metadata.json automatically)
-dbo rm Bins/app/some-file.txt
+dbo rm bins/app/some-file.txt
 
 # Remove by metadata file directly
-dbo rm Bins/app/some-file.metadata.json
+dbo rm bins/app/some-file.metadata.json
 
 # Skip confirmation prompt
-dbo rm -f Bins/app/some-file.txt
+dbo rm -f bins/app/some-file.txt
 
 # Stage server deletion without deleting local files
-dbo rm --keep-local Bins/app/some-file.txt
+dbo rm --keep-local bins/app/some-file.txt
 ```
 
 #### Directory
 
 ```bash
 # Remove a directory and all its contents (prompts for approach)
-dbo rm Bins/app/ui/
+dbo rm bins/app/ui/
 
 # Remove directory without prompts
-dbo rm -f Bins/app/ui/
+dbo rm -f bins/app/ui/
 
 # Stage deletions without removing local files/directories
-dbo rm --keep-local Bins/app/ui/
+dbo rm --keep-local bins/app/ui/
 ```
 
 When removing a directory, the CLI:
@@ -1170,6 +1244,7 @@ When removing a directory, the CLI:
 | `<path>` | File, `.metadata.json`, or directory to remove |
 | `-f, --force` | Skip all confirmation prompts |
 | `--keep-local` | Only stage server deletions, keep local files/directories |
+| `--hard` | Immediately delete local files (no `Trash/` move; legacy behavior) |
 
 #### What rm does (single file)
 
@@ -1178,7 +1253,10 @@ When removing a directory, the CLI:
 3. **Prompts for confirmation** — "Do you really want to remove this file and all of its nodes?"
 4. **Stages deletion** — adds a delete entry to `.dbo/synchronize.json`
 5. **Updates app.json** — removes the `@path/to/file.metadata.json` reference from children arrays
-6. **Deletes local files** — removes the metadata file and all referenced content/media files (unless `--keep-local`)
+6. **Soft-deletes local files** — renames files with `__WILL_DELETE__` prefix (unless `--keep-local` or `--hard`)
+7. **After `dbo push`** — successfully deleted records have their `__WILL_DELETE__` files moved to `Trash/`
+
+Use `--hard` to immediately delete files without the `Trash/` safety net.
 
 #### synchronize.json
 

package/package.json

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

package/src/commands/add.js

@@ -1,12 +1,15 @@
 import { Command } from 'commander';
-import { readFile, readdir, stat, writeFile, mkdir } from 'fs/promises';
+import { readFile, readdir, stat, writeFile, mkdir, rename } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody, checkSubmitErrors } 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 { loadAppConfig, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference } from '../lib/config.js';
+import { loadAppConfig, loadAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadConfig } from '../lib/config.js';
+import { resolveDirective, resolveTemplateCols, assembleMetadata, promptReferenceColumn, setTemplateCols, saveMetadataTemplates, loadMetadataTemplates } from '../lib/metadata-templates.js';
+import { buildUidFilename, hasUidInFilename } from '../lib/filenames.js';
+import { setFileTimestamps } from '../lib/timestamps.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { loadIgnore } from '../lib/ignore.js';
@@ -67,7 +70,7 @@ async function detectDocumentationFile(filePath) {
   if (placement !== 'root') return null;
 
   const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
-  if (!rel.startsWith('Documentation/')) return null;
+  if (!rel.startsWith('docs/')) return null;
 
   return { entity: 'extension', descriptor: 'documentation' };
 }
@@ -110,12 +113,58 @@ async function addSingleFile(filePath, client, options, batchDefaults) {
     return await submitAdd(meta, metaPath, filePath, client, options);
   }
 
-  // Step 3b: Auto-infer entity/descriptor for Documentation/ files when root placement is configured
+  // Step 3b: Directive / template path
+  const directive = resolveDirective(filePath);
+  if (directive) {
+    const { entity, descriptor } = directive;
+    const appConfig = await loadAppConfig();
+    const appJson = await loadAppJsonBaseline().catch(() => null);
+    const resolved = await resolveTemplateCols(entity, descriptor, appConfig, appJson);
+
+    if (resolved !== null) {
+      let { cols, templates } = resolved;
+
+      // Check if @reference col is known
+      const hasRefMarker = cols.some(c => c.includes('=@reference'));
+      if (!hasRefMarker) {
+        if (options.yes) {
+          console.warn(`Warning: No @reference column in template for ${entity}${descriptor ? '.' + descriptor : ''} — skipping content column. Update .dbo/metadata_templates.json to add Key=@reference.`);
+        } else {
+          const chosen = await promptReferenceColumn(cols, entity, descriptor);
+          if (chosen) {
+            cols = cols.map(c => c === chosen ? `${chosen}=@reference` : c);
+            templates = templates ?? await loadMetadataTemplates() ?? {};
+            setTemplateCols(templates, entity, descriptor, cols);
+            await saveMetadataTemplates(templates);
+          }
+        }
+      }
+
+      const { meta } = assembleMetadata(cols, filePath, entity, descriptor, appConfig);
+
+      // Determine metadata path
+      let templateMetaPath;
+      const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+      if (rel.startsWith('docs/')) {
+        // docs/ files: companion metadata goes to extension/documentation/
+        const docDir = join(process.cwd(), 'extension', 'documentation');
+        await mkdir(docDir, { recursive: true });
+        templateMetaPath = join(docDir, `${basename(filePath, extname(filePath))}.metadata.json`);
+      } else {
+        templateMetaPath = join(dirname(filePath), `${basename(filePath, extname(filePath))}.metadata.json`);
+      }
+
+      await writeFile(templateMetaPath, JSON.stringify(meta, null, 2) + '\n');
+      return await submitAdd(meta, templateMetaPath, filePath, client, options);
+    }
+  }
+
+  // Step 3c: Auto-infer entity/descriptor for Documentation/ files when root placement is configured
   const docInfo = await detectDocumentationFile(filePath);
   if (docInfo) {
     const filenameCol = await loadDescriptorFilenamePreference('documentation') || 'Name';
     const docBase = basename(filePath, extname(filePath));
-    const companionDir = join(process.cwd(), 'Extensions', 'Documentation');
+    const companionDir = join(process.cwd(), 'extension', 'documentation');
     await mkdir(companionDir, { recursive: true });
 
     const docMeta = {
@@ -337,20 +386,75 @@ async function submitAdd(meta, metaPath, filePath, client, options) {
     result = await client.postUrlEncoded('/api/input/submit', body);
   }
 
-  formatResponse(result, { json: options.json, jq: options.jq });
+  formatResponse(result, { json: options.json, jq: options.jq, verbose: options.verbose });
 
   if (!result.successful) {
     throw new Error('Add failed');
   }
 
-  // Extract UID from response and update metadata
+  // Extract UID from response and rename files to ~uid convention
   const addResults = result.payload?.Results?.Add || result.data?.Payload?.Results?.Add || [];
   if (addResults.length > 0) {
     const returnedUID = addResults[0].UID;
+    const returnedLastUpdated = addResults[0]._LastUpdated;
+
     if (returnedUID) {
-      meta.UID = returnedUID;
-      await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
-      log.success(`UID assigned: ${returnedUID}`);
+      // Check if UID is already embedded in the filename (idempotency guard)
+      const currentMetaBase = basename(metaPath);
+      if (hasUidInFilename(currentMetaBase, returnedUID)) {
+        meta.UID = returnedUID;
+        await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+        log.success(`UID already in filename: ${returnedUID}`);
+      } else {
+        // Compute new names
+        const metaDir = dirname(metaPath);
+        const currentExt = extname(filePath).substring(1);
+        const currentBase = basename(filePath, extname(filePath));
+        const newBase = buildUidFilename(currentBase, returnedUID);
+        const newFilename = currentExt ? `${newBase}.${currentExt}` : newBase;
+        const newFilePath = join(metaDir, newFilename);
+        const newMetaPath = join(metaDir, `${newBase}.metadata.json`);
+
+        // Rename content file
+        try {
+          await rename(filePath, newFilePath);
+          log.success(`Renamed: ${basename(filePath)} → ${newFilename}`);
+        } catch (err) {
+          log.warn(`  Could not rename content file: ${err.message}`);
+        }
+
+        // Update @reference in metadata
+        meta.UID = returnedUID;
+        for (const col of (meta._contentColumns || [])) {
+          const ref = meta[col];
+          if (ref && String(ref).startsWith('@')) {
+            const oldRefFile = String(ref).substring(1);
+            if (oldRefFile === basename(filePath)) {
+              meta[col] = `@${newFilename}`;
+            }
+          }
+        }
+
+        // Write and rename metadata file
+        await writeFile(newMetaPath, JSON.stringify(meta, null, 2) + '\n');
+        if (metaPath !== newMetaPath) {
+          try { await rename(metaPath, newMetaPath); } catch { /* already written */ }
+        }
+        log.dim(`  Renamed metadata: ${basename(metaPath)} → ${basename(newMetaPath)}`);
+
+        // Restore timestamps from server _LastUpdated
+        const config = await loadConfig();
+        const serverTz = config.ServerTimezone;
+        if (serverTz && returnedLastUpdated) {
+          try {
+            await setFileTimestamps(newFilePath, returnedLastUpdated, returnedLastUpdated, serverTz);
+            await setFileTimestamps(newMetaPath, returnedLastUpdated, returnedLastUpdated, serverTz);
+          } catch { /* non-critical */ }
+        }
+
+        log.success(`UID assigned: ${returnedUID}`);
+        log.dim(`  Files renamed to ~${returnedUID} convention`);
+      }
       log.dim(`  Run "dbo pull -e ${entity} ${returnedUID}" to populate all columns`);
     }
   }