@dboio/cli 0.8.0 → 0.9.2

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).
 
@@ -185,8 +219,26 @@ A gitignore-style file in the project root that controls which files and directo
 
 **Used by:**
 - `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
-- `dbo add .` — directory scanning (which files/dirs to skip)
-- `dbo push` — metadata file discovery (which dirs to skip)
+- `dbo add .` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo add file.html`)
+- `dbo push` — metadata file discovery: skips matching `.metadata.json` / `_output~*.json` files AND any record whose companion content file (`@reference`) matches an ignore pattern
+
+**Bypass:** Use `dbo input -d '...'` to submit expressions for a file that would otherwise be ignored — `dbo input` never does file discovery so `.dboignore` does not apply.
+
+**Pattern examples:**
+
+```gitignore
+# Ignore all SQL companion files (output records with CustomSQL)
+**/*.CustomSQL.sql
+
+# Ignore a specific record (by metadata file path)
+bins/app/my-draft-page.metadata.json
+
+# Ignore an entire directory
+bins/staging/
+
+# 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 `/`.
 
@@ -250,12 +302,13 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `--domain <host>` | DBO instance domain |
 | `--username <user>` | DBO username (stored for login default) |
 | `--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) |
+| `--app <shortName>` | App short name (triggers clone after init). Prompts for password and authenticates automatically before fetching app data from the server |
 | `--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` |
 
@@ -291,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) |
@@ -305,14 +359,14 @@ The project's reference domain is stored in `app.json._domain` (committed to git
 
 #### What clone does
 
-1. **Loads app JSON** — from a local file, server API, or interactive prompt
+1. **Loads app JSON** — from a local file, server API, or interactive prompt. A spinner shows progress while fetching from the server (responses can be slow as the JSON is assembled on demand)
 2. **Updates `.dbo/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`, `AppModifyKey` (if the app is locked), and `cloneSource` (the source used for this clone)
 3. **Updates `package.json`** — populates `name`, `productName`, `description`, `homepage`, and `deploy` script
 4. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
 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
+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
 
@@ -349,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)
@@ -387,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`).
 
@@ -403,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`
 
@@ -423,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**:
 
@@ -437,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
 
@@ -449,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
@@ -457,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`
@@ -729,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.
 
@@ -1015,6 +1107,8 @@ After accepting changes, file modification times are synced to the server's `_La
 
 Push local files back to DBO.io using metadata from a previous pull. This is the counterpart to `dbo content pull` and `dbo output --save`.
 
+Files and records matching `.dboignore` patterns are skipped — both by metadata file path (e.g. `*.metadata.json`) and by companion content file path (e.g. a record whose `@Content` points to an ignored `.sql` file). To push an ignored file directly, use `dbo input -d '...'` with an explicit expression.
+
 #### Round-trip workflow
 
 ```bash
@@ -1113,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:
@@ -1150,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)
 
@@ -1158,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
 
@@ -1188,6 +1286,8 @@ The next `dbo push` processes all pending deletions before pushing file changes.
 
 Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
 
+Files matching `.dboignore` patterns are skipped — both in directory-scan mode (`dbo add .`) and single-file mode (`dbo add file.html`). Use `dbo input` to create a record for an ignored file directly.
+
 #### Single file
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.8.0",
+  "version": "0.9.2",
   "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,12 +70,20 @@ 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' };
 }
 
 async function addSingleFile(filePath, client, options, batchDefaults) {
+  // Check .dboignore before doing any processing
+  const ig = await loadIgnore();
+  const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  if (ig.ignores(relPath)) {
+    log.dim(`Skipped (dboignored): ${relPath}`);
+    return null;
+  }
+
   const dir = dirname(filePath);
   const ext = extname(filePath);
   const base = basename(filePath, ext);
@@ -102,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 = {
@@ -329,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`);
     }
   }