@dboio/cli 0.10.1 → 0.11.2

package/README.md

@@ -20,7 +20,7 @@ This installs the `dbo` command globally on your system.
 ### From the repository (local development)
 
 ```bash
-cd tools/dbo-cli
+cd tools/cli
 npm install
 npm link
 ```
@@ -108,7 +108,7 @@ dbo login
 dbo status
 
 # 4. Query some data
-dbo output -e user --format json --maxrows 5
+dbo output -e user --template json_indented --maxrows 5
 
 # 5. Deploy a CSS file
 dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
@@ -124,28 +124,38 @@ When you run `dbo init --scaffold` or `dbo clone`, the following standard direct
 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
+├── lib/                # All DBO server-managed assets
+│   ├── bins/           # Assets (contents, outputs, images, HTML, CSS)
+│   │   └── app/        # Default application bin
+│   ├── automation/     # Automation entity records
+│   ├── app_version/    # App version entity records
+│   ├── entity/         # Entity definitions
+│   ├── entity_column/  # Column definitions
+│   ├── entity_column_value/ # Column value definitions
+│   ├── extension/      # Extension entity records (organized by descriptor type)
+│   │   ├── widget/
+│   │   ├── documentation/
+│   │   └── _unsupported/
+│   ├── integration/    # Integration entity records
+│   ├── security/       # Security policy records
+│   ├── security_column/ # Column-level security records
+│   ├── data_source/    # (created when data sources exist)
+│   ├── group/          # (created when groups exist)
+│   ├── site/           # (created when sites exist)
+│   └── redirect/       # (created when redirects exist)
 ├── src/                # Your actual source code (sass, typescript, etc.)
-├── tests/              # Project-level tests
-├── bins/               # Assets (contents, outputs, images, HTML, CSS)
+├── test/               # Project-level tests
 ├── 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
+├── app.json            # Clone of original app JSON with @references
+├── manifest.json       # PWA web app manifest (auto-generated from app metadata)
 ├── .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.
+> **Breaking change in 0.11.1**: All server-managed directories (`bins/`, `extension/`, `automation/`, etc.) have moved into a `lib/` subdirectory. Existing projects are migrated **automatically** on the first `dbo` command after upgrade. Also, `tests/` has been renamed to `test/`.
 
 ---
 
@@ -163,18 +173,34 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | File | Purpose | Git |
 |------|---------|-----|
 | `config.json` | Domain, app metadata, placement preferences | Committable (shared) |
-| `config.local.json` | Per-user settings: plugin scopes, future user prefs | Gitignored (per-user) |
+| `config.local.json` | Per-user settings: plugin scopes, `_completedMigrations` (system-managed) | Gitignored (per-user) |
 | `ticketing.local.json` | Stored ticket IDs for submission error recovery | Gitignored (per-user) |
 | `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) |
-| `.app_baseline.json` | App JSON baseline for delta detection (auto-generated by `dbo clone`) | Gitignored (per-machine) |
+| `synchronize.json` | Pending deletions and sync state (updated by `dbo rm` and `dbo push`) | Committable (shared) |
+| `.app_baseline.json` | Server-state snapshot for delta detection — stores column values at last clone/push so `dbo push` can detect which columns changed locally. Read-only (chmod 444); auto-migrated from legacy root `.app.json`. | 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).
 
 > **Upgrading from pre-0.9.9**: The baseline file `.app.json` in the project root has moved to `.dbo/.app_baseline.json`. Running any `dbo` command will auto-migrate the file. You can also manually remove the `.app.json` entry from your `.gitignore`.
 
+> **Upgrading from pre-0.11.0**: `TransactionKeyPreset` now applies only to records that carry a `UID` column (core assets). Data records without a UID are always submitted with `RowID` regardless of the preset. Migration 001 runs automatically on first command after upgrade and logs a one-time notice.
+
+#### Automatic migrations
+
+When the CLI version is upgraded, one-time migration scripts in `tools/cli/src/migrations/` run automatically on the first command invocation in a project directory. Completed migration IDs are recorded in `.dbo/config.local.json` under `_completedMigrations` (per-user, gitignored) so each developer runs them independently and they never re-fire.
+
+To skip migrations for a single command run:
+
+```bash
+dbo push bins/ --no-migrate
+dbo clone --app myapp --no-migrate
+```
+
+Use `dbo status` to see how many pending migrations exist.
+
 #### config.json reference
 
 ```json
@@ -185,8 +211,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
   "AppName": "My App",
   "AppShortName": "myapp",
   "cloneSource": "default",
-  "ContentPlacement": "bin",
-  "MediaPlacement": "fullpath"
+  "ContentPlacement": "bin"
 }
 ```
 
@@ -198,24 +223,39 @@ 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`) |
-| `TicketSuggestionOutput` | string | Output UID for fetching ticket suggestions during error recovery (set during `dbo init`, default `ojaie9t3o0kfvliahnuuda`) |
+| `TransactionKeyPreset` | `RowUID` \| `RowID` | Row key type (auto-set to `RowUID` during init/clone) |
+| `TicketSuggestionOutput` | string | Output UID for ticket suggestions (auto-set during init, default `ojaie9t3o0kfvliahnuuda`) |
 | `cloneSource` | `"default"` \| file path \| URL | Where the last `dbo clone` fetched app JSON from. `"default"` = server fetch via `AppShortName`; any other value = the explicit local file path or URL used. Set automatically after each successful clone. |
-| `ContentPlacement` | `bin` \| `path` \| `ask` | Where to place content files during clone |
-| `MediaPlacement` | `bin` \| `fullpath` \| `ask` | Where to place media files during clone |
+| `ContentPlacement` | `bin` \| `path` | Where to place content files during clone (default: `bin`) |
 | `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
 
-**Placement values:**
-- `bin` — Place files in the BinID-mapped directory (from `structure.json`)
-- `path` / `fullpath` — Place files in the Path/FullPath directory from the record
-- `ask` — Prompt for each file that has both a BinID and a Path/FullPath
+**File placement:** All content, media, and output files are placed by BinID into the `lib/bins/` directory structure. Records without a BinID go into `lib/bins/` root. Media always uses BinID — no FullPath option. Bins with `Name=null` (legacy) map directly to `lib/bins/` root.
+
+### Root-level project files
 
-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`
+
+Clone of the original app JSON from the server with entity entries replaced by `@path/to/*.metadata.json` references. Created by `dbo init` (empty `{}`) and populated by `dbo clone`. Committed to git.
 
 #### `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.
 
+#### `manifest.json`
+
+A [PWA web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) auto-generated during scaffolding (`dbo init` or `dbo clone`). Values are derived from `app.json` when available:
+
+| Field | Source |
+|-------|--------|
+| `name` | `<AppName> \| <domain>` |
+| `short_name` | `AppShortName` |
+| `description` | `App.Description` |
+| `start_url` / `scope` | `/app/<ShortName>/ui/` |
+| `background_color` | Extracted from the `widget` extension matching the app's `ShortName` (field `String4`), defaults to `#ffffff` |
+| `theme_color` | `#000000` |
+
+The file is only created if absent — it is never overwritten by subsequent clones, so local edits (icons, screenshots, display overrides) are preserved. A companion `manifest.metadata.json` is auto-created by `dbo push` if missing, allowing the manifest to be pushed to the server as a content record.
+
 ### `.dboignore`
 
 A gitignore-style file in the project root that controls which files and directories are excluded from CLI operations. Created automatically by `dbo init` with sensible defaults.
@@ -251,7 +291,6 @@ bins/
 .dbo/              # DBO internal
 *.dboio.json       # Export files
 app.json           # Clone output
-dbo.deploy.json    # Deployment manifest
 .git/              # Version control
 .gitignore
 node_modules/      # Node
@@ -259,7 +298,10 @@ package.json
 package-lock.json
 .claude/           # AI / tooling
 .mcp.json
-.idea/             # Editor / IDE
+.DS_Store          # Editor / IDE / OS
+Thumbs.db
+Icon\r
+.idea/
 .vscode/
 *.codekit3
 README.md          # Repo scaffolding
@@ -310,7 +352,6 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `--local` | Install Claude commands to project (`.claude/commands/`) |
 | `--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` |
 
@@ -347,7 +388,6 @@ dbo clone -e extension --descriptor-types false   # Clone extensions flat (no de
 | `-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 `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) |
@@ -367,7 +407,7 @@ The project's reference domain is stored in `app.json._domain` (committed to git
 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. 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
+7. **Downloads media files** — fetches binary files (images, CSS, fonts) from the server using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, and saves with metadata. Errors are logged to `.dbo/errors.log`
 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
@@ -526,54 +566,72 @@ project/
     MySQL-Primary.metadata.json
   site/
     MainSite.metadata.json
-  media/operator/app/...     # ← FullPath placement (when MediaPlacement=fullpath)
+  # Media files placed by BinID into bins/ (alongside content)
 ```
 
-#### Understanding the `bins/` directory structure
+#### Understanding the `lib/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 `lib/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.)
+- **`lib/bins/`** — Root directory for all bin-placed files (local organizational directory only)
+  - **`lib/bins/app/`** — Special subdirectory for the main app bin (typically the default bin)
+  - **`lib/bins/custom_name/`** — Custom bin directories (e.g., `tpl/`, `ticket_test/`, etc.)
 
-**Important: The `bins/app/` special case**
+**Important: The `lib/bins/app/` special case**
 
-The `app/` subdirectory under `bins/` is treated specially:
+The `app/` subdirectory under `lib/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 `lib/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 `lib/bins/` and `app/` from paths:
    ```
-   Local file:    bins/app/assets/css/operator.css
+   Local file:    lib/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 `lib/bins/tpl/` or `lib/bins/ticket_test/` represent actual bin hierarchies and their names are meaningful:
    ```
-   Local file:    bins/tpl/header.html
+   Local file:    lib/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 `lib/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 `lib/bins/app/assets/css/colors.css`
+- Custom bin directories like `lib/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 `lib/bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` also matches `lib/bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` matches `lib/bins/assets/css/file.css` ✓
 
 This ensures compatibility with various path formats from the server while maintaining correct local file organization.
 
+#### Media file serving (API)
+
+The DBO.io server provides three routes for serving media files:
+
+| Route | Example | Description |
+|-------|---------|-------------|
+| `/media/{app}/{path}` | `/media/todoes/App/assets/fonts/file.ttf` | Legacy FullPath — the value stored in the media record's `FullPath` column |
+| `/dir/{app}/{bins}/{file}` | `/dir/todoes/App/assets/fonts/file.ttf` | Modern BinID-based route — parses `appShortName/binHierarchy/filename` |
+| `/api/media/{uid}` | `/api/media/ujrOQPCdUEamNJdAjUQdYA` | UID-based endpoint — looks up media by unique identifier |
+
+During `dbo clone`, the CLI downloads media using a **fallback chain**:
+
+1. **FullPath** (`/media/...`) — uses the record's `FullPath` column directly
+2. **`/dir/` route** — strips the `/media/` prefix from FullPath and uses the `/dir/` route
+3. **`/api/media/{uid}`** — UID-based endpoint as last resort (when no FullPath exists)
+
+If all attempts fail, the error is logged to `.dbo/errors.log` (JSONL format) with the record's UID, filename, FullPath, and error details.
+
 #### Output hierarchy format
 
 Each root output record produces a **single compound JSON file** containing all child entities (columns, joins, filters) embedded inline:
@@ -767,16 +825,16 @@ Query data from DBO.io outputs or entities.
 dbo output qfkyyp2vxeaggdeo7dwbig
 
 # Entity query
-dbo output -e user --format json
+dbo output -e user --template json_indented
 
 # Single record
 dbo output -e user --row 10296
 
 # With filtering and sorting
-dbo output -e user --filter 'FirstName=John' --sort 'LastName:asc' --format json
+dbo output -e user --filter 'FirstName=John' --sort 'LastName:asc' --template json_indented
 
 # Contains filter
-dbo output -e content --filter 'Name:contains=color' --format json
+dbo output -e content --filter 'Name:contains=color' --template json_indented
 
 # Pagination
 dbo output -e user --page 2 --rows-per-page 25
@@ -800,18 +858,17 @@ dbo output myOutputUID --debug-sql
 | `-e, --entity <uid>` | Query by entity UID |
 | `--row <id>` | Specific row ID |
 | `--filter <expr>` | Filter expression (repeatable) |
-| `--format <type>` | Output format: `json`, `html`, `csv`, `xml`, `txt`, `pdf` |
+| `--template <value>` | Output template: `json_raw` (default), `json_indented`, `json`, `html`, `csv`, `xml`, `txt`, `pdf`, or a content UID for custom templates |
 | `--sort <expr>` | Sort expression (repeatable), e.g., `LastName:asc` |
 | `--search <expr>` | Full-text search |
 | `--page <n>` | Page number |
 | `--rows-per-page <n>` | Rows per page |
 | `--maxrows <n>` | Maximum rows |
 | `--rows <range>` | Row range, e.g., `1-10` |
-| `--template <value>` | Custom template |
 | `--limit <n>` | Maximum rows to return (preferred over `--maxrows`) |
 | `--rowcount <bool>` | Include row count: `true` (default) or `false` for performance |
 | `--display <expr>` | Show/hide template tags (repeatable), e.g., `sidebar=hide` |
-| `--format-values` | Enable value formatting in `json_raw` output |
+| `--format-values` | Enable value formatting with `--template json_raw` |
 | `--empty-response-code <code>` | HTTP status code when output returns no results |
 | `--fallback-content <expr>` | Fallback content UID for error codes, e.g., `404=contentUID` |
 | `--escape-html <bool>` | Control HTML escaping: `true` or `false` |
@@ -877,14 +934,14 @@ dbo content ykqucv0eb0ggjqgcncj6dq
 dbo content ykqucv0eb0ggjqgcncj6dq -o local/file.html
 
 # Get as plain text (disable minification)
-dbo content ykqucv0eb0ggjqgcncj6dq --format txt --no-minify
+dbo content ykqucv0eb0ggjqgcncj6dq --template txt --no-minify
 ```
 
 | Flag | Description |
 |------|-------------|
 | `<uid>` | Content UID |
 | `-o, --output <path>` | Save to local file |
-| `--format <type>` | Output format |
+| `--template <value>` | Output template (e.g., `json_raw`, `html`, `txt`, or a content UID) |
 | `--no-minify` | Disable minification |
 | `--json` | Output raw JSON |
 
@@ -1231,9 +1288,16 @@ The `@colors.css` reference tells push to read the content from that file. All o
 | `--meta-only` | Only push metadata, skip file content |
 | `--content-only` | Only push file content, skip metadata |
 | `-y, --yes` | Auto-accept all prompts |
+| `--toe-stepping <true\|false>` | Check server for conflicts before pushing (default: `true`). Set to `false` to skip the check and push unconditionally |
 | `--json` | Output raw JSON |
 | `--jq <expr>` | Filter JSON response |
 
+#### Server conflict detection (toe-stepping)
+
+By default, `dbo push` checks the live server state before submitting changes. For each record being pushed, it fetches the current server version and compares `_LastUpdated` against the local baseline. If another user has modified a record since your last `dbo clone` or `dbo push`, you'll see a conflict warning with the name of the user who made the server-side change and a per-column diff of what changed.
+
+You can then choose to overwrite the server changes or cancel and pull first. Use `--toe-stepping false` to disable the check entirely, or `--yes` to auto-accept conflicts (useful for CI/scripts).
+
 ---
 
 ### `dbo rm`
@@ -1563,7 +1627,7 @@ If no stored user info is available, it prompts for direct input. The CLI automa
 
 ### `dbo install` (alias: `dbo i`)
 
-Install or upgrade dbo-cli components including the CLI itself, plugins, and Claude Code integration.
+Install or upgrade dbo cli components including the CLI itself, plugins, and Claude Code integration.
 
 ```bash
 # Interactive — choose what to install
@@ -1621,7 +1685,7 @@ Smart behavior:
 
 ### `dbo deploy`
 
-Deploy files to DBO.io using a `dbo.deploy.json` manifest or direct arguments.
+Deploy files to DBO.io using a `.dbo/deploy_config.json` manifest or direct arguments.
 
 ```bash
 # Deploy a named entry from the manifest
@@ -1642,7 +1706,7 @@ dbo deploy img:logo
 
 | Flag | Description |
 |------|-------------|
-| `<name>` | Deployment name from `dbo.deploy.json` |
+| `<name>` | Deployment name from `.dbo/deploy_config.json` |
 | `--all` | Deploy all entries in the manifest |
 | `-C, --confirm <true\|false>` | Commit (default: `true`) |
 | `--ticket <id>` | Override ticket ID |
@@ -1654,9 +1718,9 @@ dbo deploy img:logo
 
 The `deploy` command includes the same automatic error recovery as `push`, `input`, and `add` — including ticket error handling, repository mismatch recovery, user identity prompts, and ModifyKey protection. When a stored ticket exists, you'll be prompted before the first submission (see [Pre-submission ticket prompt](#pre-submission-ticket-prompt)).
 
-#### `dbo.deploy.json` manifest
+#### `.dbo/deploy_config.json` manifest
 
-Create a `dbo.deploy.json` file in your project root to define named deployments:
+Create a `.dbo/deploy_config.json` file to define named deployments:
 
 ```json
 {
@@ -1786,7 +1850,7 @@ dbo message myUID --jq '.Successful'
 | `.[] \| .field` | Pipe: iterate then access |
 | `.["key.name"]` | Bracket notation for keys with dots |
 
-When `--jq` is used, the API request is automatically made with `_format=json`.
+When `--jq` is used, the API request is automatically made with `_template=json_raw`.
 
 ### JSON syntax highlighting
 
@@ -1871,14 +1935,15 @@ _search@ColumnName=keyword                        # search specific column
 #### Template & Format
 
 ```
-_template=json_raw                                # format name: json_raw, html, json, json_indented, csv, xml, txt, pdf
+_template=json_raw                                # system template name: json_raw, json_indented, json, html, csv, xml, txt, pdf
 _template=3iX9fHFTL064Shgol8Bktw                 # content UID (custom template)
 _format_values=true                               # enable value formatting in json_raw
-_format=json                                      # legacy format specifier
 _mime=application/json                             # override MIME/content type
 _escape_html=false                                # disable HTML escaping of data values
 ```
 
+> **`_format` is deprecated.** Do not use `_format` — use `_template` instead. The `_format` key is demoted and retained only for backwards compatibility in the API. Do not use `_format` in combination with `_template` — combining both in a single request causes broken responses.
+
 #### Display Control
 
 ```
@@ -2010,12 +2075,12 @@ dbo upload image.jpg --bin 12345 --app 67890 --ownership app --path assets/image
 
 **Before:**
 ```bash
-curl -b .cookies "https://my-domain.com/api/output/entity/user?_format=json&_filter@FirstName=John"
+curl -b .cookies "https://my-domain.com/api/output/entity/user?_template=json_indented&_filter@FirstName=John"
 ```
 
 **After:**
 ```bash
-dbo output -e user --filter 'FirstName=John' --format json
+dbo output -e user --filter 'FirstName=John' --template json_indented
 ```
 
 ### Cookie compatibility

package/bin/postinstall.js

@@ -3,6 +3,9 @@
 // Post-install hook for `npm i @dboio/cli`
 // Interactive plugin picker when TTY is available, static message otherwise.
 
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
 const DIM = '\x1b[2m';
@@ -14,12 +17,17 @@ function write(message) {
   console.log(message);
 }
 
+// Resolve path to dbo.js entrypoint — used instead of bare `dbo` command
+// because during npm postinstall the bin symlink may not be on PATH yet.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DBO_BIN = join(__dirname, 'dbo.js');
+
 // Available plugins — add new entries here as plugins are created
 const PLUGINS = [
   {
     name: 'dbo',
     label: 'Claude Code — /dbo:cli slash command',
-    command: 'dbo install --claudecommand dbo'
+    command: `node "${DBO_BIN}" install --claudecommand dbo`
   }
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.10.1",
+  "version": "0.11.2",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {
@@ -39,9 +39,9 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/dboio/api.git",
-    "directory": "tools/dbo-cli"
+    "directory": "tools/cli"
   },
-  "homepage": "https://github.com/dboio/api/tree/master/tools/dbo-cli#readme",
+  "homepage": "https://github.com/dboio/api/tree/master/tools/cli#readme",
   "bugs": {
     "url": "https://github.com/dboio/api/issues"
   }

package/plugins/claude/dbo/commands/dbo.md

@@ -74,7 +74,7 @@ Available subcommands:
 - `rm <directory>` — Remove a directory, all files, and sub-directories recursively
 - `rm -f <path>` — Remove without confirmation prompts
 - `rm --keep-local <path>` — Stage server deletions without deleting local files/directories
-- `deploy [name]` — Deploy via dbo.deploy.json manifest
+- `deploy [name]` — Deploy via .dbo/deploy_config.json manifest
 - `install` (alias: `i`) — Install or upgrade CLI, plugins, or Claude commands
 - `i dbo` or `i dbo@latest` — Install/upgrade the CLI from npm
 - `i dbo@0.4.1` — Install a specific CLI version
@@ -235,8 +235,8 @@ Flags: `--app <name>`, `--domain <host>`, `-y/--yes`, `-v/--verbose`
 3. Updates `package.json` with `name`, `productName`, `description`, `homepage`, and `deploy` script
 4. Creates directory structure from `children.bin` hierarchy → saves `.dbo/structure.json`
 5. Writes content files (decodes base64) with `*.metadata.json` into bin directories
-6. Downloads media files from server via `/api/media/{uid}` with `*.metadata.json`
-7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into project directories (`Extensions/`, `Data Sources/`, etc.) as `.metadata.json` files with optional companion content files
+6. Downloads media files from server using fallback chain: FullPath (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, with `*.metadata.json`. Errors logged to `.dbo/errors.log`
+7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into `lib/` project directories as `.metadata.json` files with optional companion content files
 8. Processes remaining entities with BinID into corresponding bin directories
 9. Saves `app.json` to project root with `@path/to/*.metadata.json` references
 

package/plugins/claude/dbo/skills/cli/SKILL.md

@@ -80,7 +80,7 @@ Available subcommands:
 - `rm <directory>` — Remove a directory, all files, and sub-directories recursively
 - `rm -f <path>` — Remove without confirmation prompts
 - `rm --keep-local <path>` — Stage server deletions without deleting local files/directories
-- `deploy [name]` — Deploy via dbo.deploy.json manifest
+- `deploy [name]` — Deploy via .dbo/deploy_config.json manifest
 - `install` (alias: `i`) — Install or upgrade CLI, plugins, or Claude commands
 - `i dbo` or `i dbo@latest` — Install/upgrade the CLI from npm
 - `i dbo@0.4.1` — Install a specific CLI version
@@ -241,8 +241,8 @@ Flags: `--app <name>`, `--domain <host>`, `-y/--yes`, `-v/--verbose`
 3. Updates `package.json` with `name`, `productName`, `description`, `homepage`, and `deploy` script
 4. Creates directory structure from `children.bin` hierarchy → saves `.dbo/structure.json`
 5. Writes content files (decodes base64) with `*.metadata.json` into bin directories
-6. Downloads media files from server via `/api/media/{uid}` with `*.metadata.json`
-7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into project directories (`Extensions/`, `Data Sources/`, etc.) as `.metadata.json` files with optional companion content files
+6. Downloads media files from server using fallback chain: FullPath (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, with `*.metadata.json`. Errors logged to `.dbo/errors.log`
+7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into `lib/` project directories as `.metadata.json` files with optional companion content files
 8. Processes remaining entities with BinID into corresponding bin directories
 9. Saves `app.json` to project root with `@path/to/*.metadata.json` references
 

package/src/commands/add.js

@@ -14,6 +14,7 @@ import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { loadStructureFile, findBinByPath } from '../lib/structure.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 export const addCommand = new Command('add')
   .description('Add a new file to DBO.io (creates record on server)')
@@ -27,8 +28,10 @@ export const addCommand = new Command('add')
   .option('--jq <expr>', 'Filter JSON response')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (targetPath, options) => {
     try {
+      await runPendingMigrations(options);
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
       // ModifyKey guard
@@ -432,6 +435,7 @@ async function submitAdd(meta, metaPath, filePath, client, options) {
     result = await client.postUrlEncoded('/api/input/submit', body);
   }
 
+  if (result.successful) await client.voidCache();
   formatResponse(result, { json: options.json, jq: options.jq, verbose: options.verbose });
 
   if (!result.successful) {