@dboio/cli 0.11.4 → 0.15.0

package/plugins/claude/dbo/docs/dbo-cli-readme.md

@@ -0,0 +1,2279 @@
+# dbo — Command Line Interface for DBO.io
+
+[![npm version](https://img.shields.io/npm/v/@dboio/cli.svg)](https://www.npmjs.com/package/@dboio/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@dboio/cli.svg)](https://www.npmjs.com/package/@dboio/cli)
+
+A terminal-based CLI for interacting with the [DBO.io](https://dbo.io) framework. Replaces raw curl commands with a clean, subcommand-driven interface for CRUD operations, querying, content deployment, media management, and more.
+
+**Available on npm:** [@dboio/cli](https://www.npmjs.com/package/@dboio/cli)
+
+## Installation
+
+### From npm (recommended)
+
+```bash
+npm install -g @dboio/cli
+```
+
+This installs the `dbo` command globally on your system.
+
+### From the repository (local development)
+
+```bash
+cd tools/cli
+npm install
+npm link
+```
+
+### Without installing (npx)
+
+```bash
+npx @dboio/cli <command>
+```
+
+> **Shorthand:** You can use `dbo i` as a shortcut for `dbo install` (similar to `npm i`).
+
+### Requirements
+
+- **Node.js 18+** (uses native `fetch` and `FormData`)
+- A DBO.io instance to connect to
+
+## Claude Code Integration
+
+The dbo CLI can be used as a `/dbo` slash command inside Claude Code sessions.
+
+### Install Claude Code commands
+
+```bash
+# Install the /dbo command into your project's .claude/commands/
+dbo install claudecommands
+
+# Install globally to ~/.claude/commands/ (shared across projects)
+dbo install claudecommands --global
+
+# Or install Claude Code CLI + commands together
+dbo install claudecode
+```
+
+Once installed, use `/dbo` in Claude Code:
+```
+/dbo pull albain3dwkofbhnd1qtd1q
+/dbo output -e user --maxrows 5
+/dbo push assets/css/
+```
+
+The plugin source lives in `plugins/claude/dbo/` at the repository root. Installed copies in `.claude/plugins/` are gitignored and managed by `dbo install`. Each plugin's installation scope (project or global) is stored per-plugin in `.dbo/config.local.json`.
+
+---
+
+## Upgrading
+
+The `dbo install` command handles both fresh installs and upgrades. If a component is already installed, it will prompt you to upgrade to the latest version.
+
+```bash
+# Upgrade CLI to latest version
+dbo install dbo@latest
+
+# Install/upgrade to a specific version
+dbo install dbo@0.4.1
+
+# Upgrade from local source
+dbo install /path/to/local/cli/src
+
+# Upgrade Claude Code commands (prompts if already installed)
+dbo install plugins
+
+# Upgrade a specific Claude command
+dbo install --claudecommand dbo
+
+# Check your version
+dbo --version
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialize configuration for the current directory
+dbo init --domain my-domain.com
+
+# 1b. Combined with cloning an app to local project bin
+dbo init --domain my-domain.com --app myapp --clone
+
+# 2. Authenticate
+dbo login
+
+# 3. Check your session
+dbo status
+
+# 4. Query some data
+dbo output -e user --template json_indented --maxrows 5
+
+# 5. Deploy a CSS file
+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)
+├── 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.)
+├── test/               # Project-level tests
+├── trash/              # Staged soft-deleted files from dbo rm
+├── docs/               # Project documentation and docs entities
+├── 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 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/`.
+
+---
+
+## 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:
+
+```bash
+~/projects/my-project/    → .dbo/ → my-domain.com
+~/projects/my-project-prod/    → .dbo/ → prod.dbo.io
+```
+
+### `.dbo/` directory contents
+
+| File | Purpose | Git |
+|------|---------|-----|
+| `config.json` | Domain, app metadata, placement preferences | Committable (shared) |
+| `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) |
+| `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) |
+| `scripts.json` | Build/push lifecycle hooks (see [Script Hooks](#script-hooks)) | Committable (shared) |
+| `scripts.local.json` | Per-user hook overrides | Gitignored (per-user) |
+
+`dbo init` automatically adds `.dbo/credentials.json`, `.dbo/cookies.txt`, `.dbo/config.local.json`, `.dbo/ticketing.local.json`, and `.dbo/scripts.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.
+
+> **Upgrading to 0.13.3+**: Entity and extension companion files no longer include `~UID` in the filename. Migration 007 automatically renames legacy `name~uid.Column.ext` files to `name.Column.ext` and updates `@references` in metadata.
+
+> **Upgrading to 0.14.0+**: Metadata files now use `name.metadata~uid.json` instead of `name~uid.metadata.json`. The UID has moved from the base name into the `.metadata~uid` suffix. Migration 008 automatically renames all metadata files. Output child companions use index-based naming (`Sales.column.CustomSQL.sql`, `Sales.column-1.CustomSQL.sql`) instead of UID-based naming.
+>
+> | Record type | Example metadata file |
+> |---|---|
+> | Content | `colors.metadata~abc123.json` |
+> | Media | `logo.png.metadata~def456.json` |
+> | Output | `Sales.metadata~ghi789.json` |
+> | Extension | `MyExtension.metadata~jkl012.json` |
+
+#### 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
+{
+  "domain": "my-domain.com",
+  "AppID": 10198,
+  "AppUID": "abc123",
+  "AppName": "My App",
+  "AppShortName": "myapp",
+  "cloneSource": "default",
+  "ContentPlacement": "bin"
+}
+```
+
+| Key | Values | Description |
+|-----|--------|-------------|
+| `domain` | hostname | DBO.io instance to connect to |
+| `AppID` | number | App ID (set by `dbo clone`, used by `dbo add`/`dbo input`) |
+| `AppUID` | string | App UID |
+| `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 (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` | Where to place content files during clone (default: `bin`) |
+| `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
+
+**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
+
+#### `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.
+
+**Used by:**
+- `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
+- `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 `/`.
+
+**Default patterns:**
+
+```gitignore
+.dbo/              # DBO internal
+*.dboio.json       # Export files
+app.json           # Clone output
+.git/              # Version control
+.gitignore
+node_modules/      # Node
+package.json
+package-lock.json
+.claude/           # AI / tooling
+.mcp.json
+.DS_Store          # Editor / IDE / OS
+Thumbs.db
+Icon\r
+.idea/
+.vscode/
+*.codekit3
+README.md          # Repo scaffolding
+SETUP.md
+```
+
+Edit `.dboignore` to add or remove patterns. Committed to git and shared across users.
+
+### Legacy migration
+
+If your project uses the older `.domain`, `.username`, `.password`, `.cookies` files, `dbo init` will detect them and offer to migrate automatically.
+
+### Environment variables
+
+Environment variables override file-based configuration:
+
+- `DBO_DOMAIN` — target domain
+- `DBO_USERNAME` — username
+- `DBO_PASSWORD` — password
+
+---
+
+## Commands
+
+### `dbo init`
+
+Initialize DBO CLI configuration for the current directory.
+
+```bash
+dbo init                                              # interactive prompts
+dbo init --domain my-domain.com                       # non-interactive
+dbo init --domain my-domain.com --username me@co.io   # with credentials
+dbo init --force                                      # overwrite existing config
+dbo init --domain my-domain.com --app myapp --clone   # init + clone an app
+dbo init --domain my-domain.com -y                    # skip all prompts
+dbo init --scaffold                                   # scaffold dirs (prompts for domain)
+dbo init --scaffold --yes                             # scaffold dirs non-interactively
+```
+
+| Flag | Description |
+|------|-------------|
+| `--domain <host>` | DBO instance domain |
+| `--username <user>` | DBO username (stored for login default) |
+| `--force` | Overwrite existing configuration. 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). 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_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) |
+| `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
+| `--non-interactive` | Alias for `--yes` |
+
+---
+
+### `dbo clone`
+
+Clone an app from DBO.io to a local project structure. Creates directories, files, metadata, and populates `config.json` and `package.json`.
+
+```bash
+# Clone using config (AppShortName from .dbo/config.json)
+dbo clone
+
+# Clone from a local JSON export file
+dbo clone /path/to/app_export.json
+
+# Clone from server by app short name
+dbo clone --app myapp
+
+# Combined with init
+dbo init --domain my-domain.com --app myapp --clone
+
+# Extension descriptor sub-directory handling
+dbo clone -e extension                            # Clone all extensions (sorted by descriptor type)
+dbo clone -e extension --documentation-only       # Clone only documentation extensions
+dbo clone -e extension --documentation-only --force  # Reset documentation preferences and re-clone
+dbo clone -e extension --descriptor-types false   # Clone extensions flat (no descriptor sorting)
+```
+
+| Flag | Description |
+|------|-------------|
+| `<source>` | Local file path or URL to load app JSON from (optional positional argument) |
+| `--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 `extension/` layout |
+| `--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) |
+| `-v, --verbose` | Show HTTP request details |
+
+#### Domain change detection
+
+When cloning with a different domain than the project's reference domain (`app.json._domain` or `config.json.domain`), the CLI warns before proceeding. When `TransactionKeyPreset=RowID`, this escalates to a critical error because numeric IDs are not unique across domains — pushing to the wrong domain can corrupt records. In non-interactive mode (`-y`), RowUID domain changes proceed with a warning, but RowID domain changes throw a hard error.
+
+The project's reference domain is stored in `app.json._domain` (committed to git) during clone, giving the CLI a stable cross-user baseline.
+
+#### What clone does
+
+1. **Loads app JSON** — from a local file, server API, or interactive prompt. 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. 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 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
+11. **Orphan cleanup** — any local `.metadata.json` files whose UID is absent from the server response are automatically moved to `trash/` along with their companion content and media files. This prevents stale records (deleted server-side) from causing false positives in `dbo push`. Skipped during `--entity-filter` clones
+
+#### Clone source tracking
+
+After every successful clone, the source is persisted as `cloneSource` in `.dbo/config.json`:
+
+- `"default"` — app JSON was fetched from the server using `AppShortName` (the normal flow)
+- A file path or URL — set when an explicit `<source>` argument was provided (e.g. `dbo clone /path/to/export.json`)
+
+On subsequent clones, if you provide an explicit source that **differs** from the stored `cloneSource`, the CLI warns and asks for confirmation before proceeding:
+
+```
+  ⚠  This project was previously cloned from: default
+     Requested source:                        /path/to/export.json
+? Clone from the new source anyway? This will update the stored clone source. (y/N)
+```
+
+Use `--force` or `-y` to skip the prompt and override without being asked.
+
+If the initial clone attempt fails (network error, file not found, empty response), the CLI prompts for a fallback source to retry with instead of aborting:
+
+```
+  ⚠  Source did not return expected results: No app found with ShortName "myapp"
+? Enter another local file path or URL to retry (or leave empty to abort):
+```
+
+#### Change detection on re-clone
+
+When cloning an app that was already cloned locally, the CLI detects existing files and compares modification times against the server's `_LastUpdated`. You'll be prompted to overwrite, compare differences, or skip — same as `dbo pull`. Use `-y` to auto-accept all changes.
+
+#### Collision detection
+
+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"
+? Which record should create this file?
+❯ [content] colors (UID: abc123)
+  [media] colors.css (UID: def456)
+```
+
+The rejected record is automatically staged for deletion in `.dbo/synchronize.json`. Run `dbo push` to delete it from the server.
+
+In non-interactive mode (`-y`), the first record is kept and others are auto-staged for deletion.
+
+#### Stale media cleanup
+
+During media downloads, files returning 404 (no longer exist on the server) are collected as "stale records". After all downloads complete, you'll be prompted to stage them for deletion:
+
+```
+Found 3 stale media record(s) (404 - files no longer exist on server)
+? Stage these 3 stale media records for deletion? (y/N)
+```
+
+This helps keep your app clean by removing database records for media files that have been deleted from the server.
+
+In non-interactive mode (`-y`), stale cleanup is skipped (conservative default).
+
+#### Path resolution
+
+When a content record has both `Path` and `BinID`, the CLI prompts:
+```
+Where do you want me to place filename.ext?
+  1. Into the Path of /path/from/path/column
+  2. Into the BinID of 12345 (mapped BinName → bin/directory)
+```
+
+#### Entity directory processing
+
+Entity types that correspond to project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are processed into their named directories without requiring a `BinID`:
+
+| Entity Key | Directory |
+|------------|-----------|
+| `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`).
+
+If any columns contain base64-encoded content, the CLI prompts to extract them as companion files. Extracted columns produce files named `<name>.<Column>.<ext>` alongside the metadata, with `@reference` entries in the metadata and a `_contentColumns` array.
+
+**Companion file naming convention:** Only `.metadata.json` files carry the `~UID` suffix (e.g. `Add-Asst-Execute-Security~wxl6ivcwfkix3zgantszjg.metadata.json`). Companion content files use the natural base name without `~UID` (e.g. `Add-Asst-Execute-Security.String16.js`). If two records share the same name within a directory, the second gets a `-1` suffix (e.g. `Add-Asst-Execute-Security-1.String16.js` with metadata `Add-Asst-Execute-Security-1~otheruid.metadata.json`). Migration 007 automatically renames legacy `~UID` companion files to the natural convention.
+
+Use `-y` to skip prompts (uses `Name` column, no content extraction).
+
+#### Extension descriptor sub-directories
+
+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 `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`
+
+**Config keys** (saved per descriptor in `config.json`):
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `Extension_<descriptor>_FilenameCol` | `Extension_documentation_FilenameCol` | Filename column for that descriptor type |
+| `Extension_<descriptor>_ContentExtractions` | `Extension_documentation_ContentExtractions` | Content extraction preferences per column |
+| `ExtensionDocumentationMDPlacement` | `"inline"` or `"root"` | Where to place documentation MD files |
+
+**Documentation alternate placement**: When extracting MD content from `documentation` descriptor extensions, the CLI offers a choice:
+
+- **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., `@/docs/my-doc.md`) so `dbo push` can locate them regardless of where the metadata lives.
+
+**Entity filter support**:
+
+```bash
+dbo clone -e extension --documentation-only         # Clone only documentation extensions
+dbo clone -e extension --documentation-only --force  # Reset documentation preferences and re-clone
+dbo clone -e extension                               # Clone all extensions (all descriptor types)
+dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
+```
+
+**`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
+
+```
+project/
+  .dbo/
+    config.json              # Updated with app metadata
+    structure.json           # Bin directory mapping
+  .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
+    app/                     # ← directory from children.bin
+      thomas-scratch.md
+      thomas-scratch.metadata.json
+      CurrentTicketID.cs
+      CurrentTicketID.metadata.json
+    ticket_test/             # ← another bin directory
+      ...
+  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)
+  docs/                      # ← root-placed documentation MD files (optional)
+    MyDoc.md
+  data_source/
+    MySQL-Primary.metadata.json
+  site/
+    MainSite.metadata.json
+  # Media files placed by BinID into bins/ (alongside content)
+```
+
+#### Understanding the `lib/bins/` directory structure
+
+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:**
+
+- **`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 `lib/bins/app/` special case**
+
+The `app/` subdirectory under `lib/bins/` is treated specially:
+
+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 `lib/bins/` and `app/` from paths:
+   ```
+   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 `lib/bins/tpl/` or `lib/bins/ticket_test/` represent actual bin hierarchies and their names are meaningful:
+   ```
+   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 `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 `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:
+
+```
+bins/app/
+  _output~Sales~abc123.json          ← root output with inline children
+  _output~Sales~abc123.column~col1.CustomSQL.sql  ← companion SQL file
+```
+
+The root JSON structure:
+```json
+{
+  "_entity": "output",
+  "UID": "abc123",
+  "Name": "Sales",
+  "children": {
+    "column": [
+      { "_entity": "output_value", "UID": "col1", "Title": "Amount", "children": { "column": [], "join": [], "filter": [] } }
+    ],
+    "join": [],
+    "filter": [
+      { "_entity": "output_value_filter", "UID": "f1", "ShortName": "Active", "children": { "column": [], "join": [], "filter": [] } }
+    ]
+  }
+}
+```
+
+Key points:
+- All three child keys (`column`, `join`, `filter`) are always present (empty arrays when unused)
+- Each child retains `_entity` set to its physical table name for push routing
+- Children nest recursively following FK relationships (e.g. a column can have filters)
+- `CustomSQL` content is extracted to companion `.sql` files per extraction rules
+- Re-cloning moves orphaned old-format child `.json` files to `/trash`
+
+#### 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`
+
+Authenticate with a DBO.io instance and store the session cookie.
+
+After successful authentication, the CLI automatically fetches and stores the current user's ID, UID, name, and email in `.dbo/credentials.json`. The ID and UID are used for automatic retry when server submissions require user identity (see [Automatic error recovery](#automatic-error-recovery)). The name and email are used to populate `package.json` author fields during `dbo clone`.
+
+> **Note:** User info is currently retrieved via a separate API call after login. This is a temporary workaround — the authentication endpoint should include user info in its response directly.
+
+```bash
+dbo login                                         # uses stored credentials
+dbo login -u user@example.com -p myPassword       # explicit credentials
+dbo login -e user@example.com                     # authenticate by email
+dbo login --phone +15551234567 -p myPassword      # authenticate by phone
+dbo login --passkey abc123def                     # authenticate with passkey
+```
+
+| Flag | Description |
+|------|-------------|
+| `-u, --username <value>` | Username identity |
+| `-e, --email <value>` | Email identity |
+| `--phone <value>` | Phone number identity |
+| `-p, --password <value>` | Password credential |
+| `--passkey <value>` | Passkey credential (rotating API key) |
+| `--domain <host>` | Override domain for this request |
+
+---
+
+### `dbo logout`
+
+Log out and clear the local session cookie.
+
+```bash
+dbo logout
+```
+
+---
+
+### `dbo status`
+
+Show current configuration, domain, and session status.
+
+```bash
+dbo status
+```
+
+Output:
+```
+  Initialized: Yes (.dbo/)
+  Domain: my-domain.com
+  Username: user@example.com
+  User ID: 10296
+  Directory: /Users/me/projects/operator
+  Session: Active (expires: 2026-03-15T10:30:00.000Z)
+  Cookies: /Users/me/projects/operator/.dbo/cookies.txt
+
+  Claude Code Plugins:
+  dbo: ✓ global (~/.claude/commands/dbo.md)
+```
+
+User ID is populated by `dbo login`. If it shows "(not set)", run `dbo login` to fetch it.
+
+Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `.dbo/config.local.json`.
+
+---
+
+### `dbo input`
+
+Submit CRUD operations (add, edit, delete records) to DBO.io. This is the core data manipulation command.
+
+```bash
+# Add a record
+dbo input -d 'RowID:add1;column:user.FirstName=John' -d 'RowID:add1;column:user.LastName=Doe'
+
+# Edit a record by UID
+dbo input -d 'RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css'
+
+# Delete a record
+dbo input -d 'RowID:del10062;entity:user=true'
+
+# Multiple operations in one call
+dbo input -d 'RowID:add1;column:user.LastName=Doe&RowUID:abc;column:content.Content@file.css'
+
+# With file upload (multipart)
+dbo input -d 'RowID:add1;column:media.BinID=12345' -f file=@path/to/image.jpg
+
+# Validation only (no commit)
+dbo input -d 'RowID:add1;column:user.FirstName=John' --confirm false
+
+# With ticket ID override
+dbo input -d 'RowID:add1;column:content.Name=test' --ticket abc123
+
+# See the HTTP request being made
+dbo input -d 'RowUID:abc;column:content.Content@file.css' -v
+```
+
+| Flag | Description |
+|------|-------------|
+| `-d, --data <expr>` | DBO input expression (repeatable) |
+| `-f, --file <field=@path>` | File attachment for multipart upload (repeatable) |
+| `-C, --confirm <true\|false>` | Commit changes (default: `true`). Use `false` for validation only |
+| `--ticket <id>` | Override ticket ID (`_OverrideTicketID`) |
+| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Row key type (`RowUID` or `RowID`) — no-op for `-d` passthrough, available for consistency |
+| `--login` | Auto-login user created by this submission |
+| `--transactional` | Use transactional processing |
+| `--json` | Output raw JSON response |
+| `-v, --verbose` | Show HTTP request details |
+| `--domain <host>` | Override domain |
+
+#### Input expression syntax
+
+```
+RowID:identifier;column:entity.ColumnName=value        # direct value
+RowUID:identifier;column:entity.ColumnName@filepath    # value from file
+RowID:delIdentifier;entity:entityName=true             # delete
+```
+
+The `@filepath` syntax reads the file contents and uses them as the column value. This is how CSS, JS, HTML, and other text content is deployed to DBO.
+
+---
+
+### `dbo output`
+
+Query data from DBO.io outputs or entities.
+
+```bash
+# Custom output by UID
+dbo output qfkyyp2vxeaggdeo7dwbig
+
+# Entity query
+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' --template json_indented
+
+# Contains filter
+dbo output -e content --filter 'Name:contains=color' --template json_indented
+
+# Pagination
+dbo output -e user --page 2 --rows-per-page 25
+
+# Save results to local files (interactive)
+dbo output -e content --filter 'AppID=10100' --save
+
+# Save results to local files (non-interactive / scripting)
+dbo output -e content --save-filename Name --save-path Path --save-content Content --save-extension Extension
+
+# Entity metadata
+dbo output -e user --meta
+
+# Debug SQL
+dbo output myOutputUID --debug-sql
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Output UID (positional argument) |
+| `-e, --entity <uid>` | Query by entity UID |
+| `--row <id>` | Specific row ID |
+| `--filter <expr>` | Filter expression (repeatable) |
+| `--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` |
+| `--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 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` |
+| `--mime <type>` | Override MIME/content type |
+| `--strict` | Strict error mode |
+| `--confirm` | Confirmation flag |
+| `--include <expr>` | Include token |
+| `--no-transaction` | Disable transaction wrapping |
+| `--skip <phase>` | Skip execution phases (repeatable, admin-only) |
+| `--profile` | Enable MiniProfiler output |
+| `--debug` | Include debug info |
+| `--debug-sql` | Include SQL debug info |
+| `--debug-verbose` | Verbose debug output |
+| `--debug-analysis` | Analysis debug output |
+| `--meta` | Use meta output endpoint |
+| `--meta-column <uid>` | Column metadata |
+| `--save` | Interactive save-to-disk mode |
+| `--save-filename <col>` | Column for filenames (non-interactive) |
+| `--save-path <col>` | Column for file path (non-interactive) |
+| `--save-content <col>` | Column for file content (non-interactive) |
+| `--save-extension <col>` | Column or literal extension (non-interactive) |
+| `--json` | Output raw JSON |
+| `-v, --verbose` | Show HTTP request details |
+
+#### Save to Disk (`--save`)
+
+The save-to-disk feature fetches data and persists records as local files. It uses an interactive flow with arrow-key selection prompts:
+
+1. **Filename column** — which column value becomes the filename (default: `Name` or `UID`)
+2. **Path column** — which column contains the directory path (builds local directories)
+3. **Content column(s)** — which column(s) to save as file content (skip for metadata only)
+4. **Extension** — use an entity column or specify manually
+
+Each record produces:
+- 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.
+
+---
+
+### `dbo content`
+
+Get, deploy, or pull content from DBO.io.
+
+```bash
+# Get content by UID
+dbo content ykqucv0eb0ggjqgcncj6dq
+
+# Save content to a local file
+dbo content ykqucv0eb0ggjqgcncj6dq -o local/file.html
+
+# Get as plain text (disable minification)
+dbo content ykqucv0eb0ggjqgcncj6dq --template txt --no-minify
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID |
+| `-o, --output <path>` | Save to local file |
+| `--template <value>` | Output template (e.g., `json_raw`, `html`, `txt`, or a content UID) |
+| `--no-minify` | Disable minification |
+| `--json` | Output raw JSON |
+
+#### `dbo content deploy`
+
+Deploy a local file's contents to a DBO content record.
+
+```bash
+dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
+dbo content deploy rncjivlghu65bmkbjnxynq assets/js/app.js
+dbo content deploy abc123 docs/readme.md --ticket myTicket
+dbo content deploy abc123 test.html --confirm false    # validate only
+dbo content deploy abc123 image.png --multipart        # binary file upload
+```
+
+This is a shorthand for:
+```bash
+dbo input -d 'RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css'
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID (RowUID) |
+| `<filepath>` | Local file path |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--multipart` | Use multipart/form-data upload (for binary files) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
+
+#### `dbo content pull`
+
+Pull content records from DBO to local files. Uses the content entity's well-known columns (`Name`, `Path`, `Content`, `Extension`) automatically — no interactive prompts.
+
+```bash
+# Pull a single content record
+dbo content pull ykqucv0eb0ggjqgcncj6dq
+
+# Pull all content for an app
+dbo content pull --filter 'AppID=10100'
+
+# Pull with row limit
+dbo content pull --filter 'AppID=10100' --maxrows 50
+```
+
+Creates local files matching the content entity's `Path` and `Extension` columns:
+```
+css/
+  colors.css                    # content.Content value
+  colors.metadata.json          # all column values as JSON
+js/
+  app.js
+  app.metadata.json
+```
+
+#### Smart change detection
+
+When pulling records that already exist locally, the CLI compares your local file modification times against the server's `_LastUpdated` timestamp. If the server has newer data, you'll be prompted:
+
+1. **Overwrite** — replace local with server version
+2. **Compare** — show a line-by-line diff and selectively merge
+3. **Skip** — keep local unchanged
+4. **Overwrite all** / **Skip all** — bulk action for remaining files
+
+After writing, file modification times are synced to the server's `_LastUpdated` to establish a sync point for future comparisons. Use `dbo diff` to compare without pulling.
+
+---
+
+### `dbo media`
+
+Get media files from DBO.io.
+
+```bash
+# Get media by UID
+dbo media albain3dwkofbhnd1qtd1q
+
+# Save to local file
+dbo media albain3dwkofbhnd1qtd1q -o logo.png
+
+# Get by numeric ID
+dbo media --id 12345 -o file.jpg
+
+# Get by path
+dbo media --path assets/images/logo.png -o logo.png
+
+# Force download
+dbo media albain3dwkofbhnd1qtd1q --download -o file.pdf
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Media UID |
+| `--id <id>` | Media by numeric ID |
+| `--path <path>` | Media by directory path |
+| `-o, --output <path>` | Save to local file |
+| `--download` | Force download (attachment disposition) |
+
+---
+
+### `dbo upload`
+
+Upload a binary file to DBO.io.
+
+```bash
+dbo upload image.jpg --bin 12345 --app 67890 --ownership app --path assets/images
+dbo upload logo.svg --bin 12345 --app 67890 --ownership app --path assets/gfx --name brand-logo
+dbo upload doc.pdf --bin 12345 --app 67890 --ownership user --path docs --confirm false
+```
+
+| Flag | Description |
+|------|-------------|
+| `<filepath>` | Local file to upload |
+| `--bin <id>` | BinID (required) |
+| `--app <id>` | AppID (required) |
+| `--ownership <type>` | Ownership: `app`, `user`, or `system` (required) |
+| `--path <dir>` | Media path (required) |
+| `--name <value>` | Override filename |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+---
+
+### `dbo message`
+
+Send messages via DBO.io (email, SMS/MMS, chatbot).
+
+```bash
+# Send an email
+dbo message emailTemplateUID
+
+# Send a chatbot message with thread
+dbo message chatbotTemplateUID --thread conversation123
+
+# Validate without sending
+dbo message emailTemplateUID --confirm false
+```
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Content UID for the message template |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--thread <id>` | Thread ID for chatbot conversations |
+| `--json` | Output raw JSON |
+
+---
+
+### `dbo cache`
+
+Manage the DBO.io cache.
+
+```bash
+# List all cached items
+dbo cache list
+
+# List with metadata
+dbo cache list --metadata
+
+# Refresh a specific cache key
+dbo cache refresh --key 'content:myContentUID'
+```
+
+#### `dbo cache list`
+
+| Flag | Description |
+|------|-------------|
+| `--metadata` | Include cache provider metadata |
+| `--json` | Output raw JSON |
+
+#### `dbo cache refresh`
+
+| Flag | Description |
+|------|-------------|
+| `--key <value>` | Cache key to refresh (required) |
+| `--part <value>` | Cache partition |
+
+---
+
+### `dbo instance`
+
+Manage DBO.io instances.
+
+```bash
+# Export the current instance
+dbo instance export
+
+# Build an instance
+dbo instance build instanceUID
+
+# Validate without executing
+dbo instance export --confirm false
+```
+
+#### `dbo instance export`
+
+| Flag | Description |
+|------|-------------|
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+#### `dbo instance build <uid>`
+
+| Flag | Description |
+|------|-------------|
+| `<uid>` | Instance UID |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+
+---
+
+### `dbo diff`
+
+Compare local files against their server versions and selectively merge changes. This is a one-directional comparison: only server → local changes can be accepted. To push local changes back, use `dbo push`.
+
+```bash
+# Compare all records in the current directory
+dbo diff
+
+# Compare a specific file
+dbo diff assets/css/colors.css
+
+# Compare all records in a directory
+dbo diff assets/
+
+# Display diffs without prompting
+dbo diff --no-interactive
+
+# Accept all server changes without prompting
+dbo diff -y
+```
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | File, directory, or `.` (default: current directory) |
+| `--no-interactive` | Show diffs without prompting to accept |
+| `-y, --yes` | Accept all server changes automatically |
+| `-v, --verbose` | Show HTTP request details |
+| `--domain <host>` | Override domain |
+
+#### Interactive mode
+
+For each file with differences, you can:
+1. **Accept all changes** — overwrite local with server version
+2. **Cherry-pick fields** — accept/skip individual field changes
+3. **Skip** — keep local files unchanged
+4. **Accept all remaining** — auto-accept for all remaining files
+5. **Skip all remaining** — skip all remaining files
+
+#### Diff output
+
+Shows a unified diff format with color coding:
+- Red lines (`-`) — content only in your local file
+- Green lines (`+`) — content only on the server
+- Cyan headers — hunk markers showing line positions
+
+After accepting changes, file modification times are synced to the server's `_LastUpdated` timestamp to establish a new sync point.
+
+---
+
+### `dbo push`
+
+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
+# 1. Pull content to local files
+dbo content pull --filter 'AppID=10100' --maxrows 10
+
+# 2. Edit files locally
+vim css/colors.css
+
+# 3. Push changes back to DBO
+dbo push css/colors.css
+```
+
+#### Single file
+
+```bash
+# Push a single file (uses companion .metadata.json)
+dbo push assets/js/main.js
+
+# Validate without submitting
+dbo push assets/js/main.js --confirm false
+
+# Push only the file content, not metadata columns
+dbo push assets/js/main.js --content-only
+
+# Push only metadata changes, skip file content
+dbo push assets/js/main.js --meta-only
+```
+
+The push command finds `assets/js/main.metadata.json`, reads the UID and entity, and builds input expressions for all columns.
+
+#### Directory (recursive)
+
+```bash
+# Push all changed records in the current directory
+dbo push
+
+# Push all records in a specific directory
+dbo push assets/
+
+# Push with auto-accept for all prompts
+dbo push assets/ -y
+```
+
+Recursively finds all `*.metadata.json` files, verifies `@filename` references exist, and pushes each record.
+
+#### Path mismatch detection
+
+If you move a file to a different directory after pulling, the push detects the mismatch:
+
+```
+  ⚠ Path mismatch for "main":
+    Metadata Path: css/main.css
+    Current path:  assets/css/main.css
+  Update Path column to "assets/css/main.css"? (Y/n)
+```
+
+The `--yes` flag auto-accepts path updates.
+
+#### Metadata format
+
+After a pull, metadata files contain `@filename` references for content columns:
+
+```json
+{
+  "_entity": "content",
+  "_contentColumns": ["Content"],
+  "UID": "abc123",
+  "Name": "colors",
+  "Content": "@colors.css",
+  "Extension": "CSS",
+  "Path": "css/colors.css",
+  "Type": "Code"
+}
+```
+
+The `@colors.css` reference tells push to read the content from that file. All other values are pushed as literal column values.
+
+| Flag | Description |
+|------|-------------|
+| `[path]` | File or directory to push (default: current directory) |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
+| `--meta-only` | Only push metadata, skip file content |
+| `--content-only` | Only push file content, skip metadata |
+| `-y, --yes` | Auto-accept all prompts |
+| `--toe-stepping <true\|false>` | Check server for conflicts before pushing (default: `true`). Set to `false` to skip the check and push unconditionally |
+| `--no-scripts` | Bypass all script hooks; run default push pipeline |
+| `--no-build` | Skip the build phase; run push phase only |
+| `--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 tag`
+
+Apply macOS Finder color tags or Linux gio emblems to companion files based on their sync status relative to the server. Tags are automatically refreshed after `dbo clone` and `dbo push`.
+
+| Tag | Color | Meaning |
+|-----|-------|---------|
+| `dbo:Synced` | 🟢 Green | File matches server — no local changes |
+| `dbo:Modified` | 🔵 Blue | Local edits not yet pushed |
+| `dbo:Untracked` | 🟡 Yellow | No metadata — not yet added with `dbo add` |
+| `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
+
+```bash
+dbo tag                  # Refresh tags for all project files
+dbo tag --clear          # Remove all dbo:* tags (preserves other Finder tags)
+dbo tag --status         # Show counts per category
+dbo tag --verbose        # Log each file and its status
+dbo tag path/to/dir      # Tag a specific file or directory subtree
+dbo tag --enable         # Enable automatic tagging after clone/push (default)
+dbo tag --disable        # Disable automatic tagging
+```
+
+Tagging is silently skipped on Windows and unsupported platforms. Only macOS (Finder color tags via `xattr`) and Linux (gio emblems) are supported. The `--clear` flag only removes `dbo:*` prefixed tags, preserving any user-applied Finder tags.
+
+---
+
+### `dbo rm`
+
+Remove a file or directory locally and stage server deletions for the next `dbo push`. Similar to `git rm`.
+
+#### Single file
+
+```bash
+# Remove a content file (finds companion .metadata.json automatically)
+dbo rm bins/app/some-file.txt
+
+# Remove by metadata file directly
+dbo rm bins/app/some-file.metadata.json
+
+# Skip confirmation prompt
+dbo rm -f bins/app/some-file.txt
+
+# Stage server deletion without deleting local files
+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/
+
+# Remove directory without prompts
+dbo rm -f bins/app/ui/
+
+# Stage deletions without removing local files/directories
+dbo rm --keep-local bins/app/ui/
+```
+
+When removing a directory, the CLI:
+1. Looks up the BinID from `.dbo/structure.json`
+2. Recursively collects all sub-directories (processed leaves-first)
+3. Prompts: "Remove all files and directories", "Prompt for each file", or "Cancel"
+4. Stages each file's deletion, then each bin's deletion (`entity:bin`)
+5. Removes the local directory (unless `--keep-local`)
+
+| Flag | Description |
+|------|-------------|
+| `<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)
+
+1. **Resolves metadata** — if given a content file, finds the companion `.metadata.json`
+2. **Reads row ID** — uses `_id` (shorthand) or derives from entity (e.g., `ContentID`, `MediaID`)
+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. **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
+
+Pending deletions are stored in `.dbo/synchronize.json`:
+
+```json
+{
+  "delete": [
+    {
+      "UID": "a2dxvg23rk6xsmnum7pdxa",
+      "RowID": 16012,
+      "entity": "content",
+      "name": "nima-test-test",
+      "expression": "RowID:del16012;entity:content=true"
+    }
+  ],
+  "edit": [],
+  "add": []
+}
+```
+
+The next `dbo push` processes all pending deletions before pushing file changes. Successful deletions are removed from synchronize.json; failures remain staged for retry.
+
+---
+
+### `dbo add`
+
+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
+# Add a file (interactive metadata setup if no .metadata.json exists)
+dbo add assets/css/colors.css
+
+# Add with auto-accept prompts
+dbo add assets/css/colors.css -y
+
+# Add with ticket ID
+dbo add assets/css/colors.css --ticket abc123
+```
+
+If the file has no companion `.metadata.json`, an interactive wizard prompts for the entity name, content column, AppID, BinID, SiteID, and Path. It then creates the metadata file and submits the insert.
+
+#### Directory scan
+
+```bash
+# Scan current directory for un-added files
+dbo add .
+
+# Scan a specific directory
+dbo add assets/
+```
+
+Recursively finds files that either have no `.metadata.json` companion or have metadata without `_CreatedOn` (never been on the server). Lists them and prompts for confirmation before adding.
+
+When adding multiple files, the entity and column defaults from the first file are reused for subsequent files.
+
+#### After adding
+
+After a successful add, the server returns a UID which is written back to the metadata file. To populate all server-side columns (like `_CreatedOn`, `Extension`, etc.), run:
+
+```bash
+dbo pull -e content <uid>
+```
+
+#### Metadata generated by add
+
+Minimal (no optional fields provided):
+```json
+{
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+With optional fields (only included if the user provides values during the wizard):
+```json
+{
+  "AppID": 10100,
+  "BinID": 11045,
+  "SiteID": 10061,
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+The `@colors.css` reference tells the CLI to read the file content from `colors.css` in the same directory.
+
+| Flag | Description |
+|------|-------------|
+| `<path>` | File or `.` to scan current directory |
+| `-C, --confirm <true\|false>` | Commit (default: `true`) |
+| `--ticket <id>` | Override ticket ID |
+| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Row key type (`RowUID` or `RowID`) — `add` always uses `RowID:add1` for new records regardless |
+| `-y, --yes` | Auto-accept all prompts |
+| `--json` | Output raw JSON |
+| `--jq <expr>` | Filter JSON response |
+
+#### Column filtering
+
+The `add` and `push` commands never submit these server-managed columns:
+- `_CreatedOn`, `_LastUpdated` — set by the server
+- `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
+- `UID` — assigned by the server on insert
+- `_id` — internal database ID
+
+---
+
+### Automatic error recovery
+
+The `input`, `push`, and `add` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
+
+#### Ticket error recovery
+
+When the server returns a `ticket_error` (record update requires a Ticket ID), the CLI prompts with interactive recovery options:
+
+```
+⚠ This record update requires a Ticket ID.
+? Record update requires a Ticket ID:
+❯ Apply a Ticket ID to this record and resubmit
+  Apply a Ticket ID to all updates in this transaction, and update my current Ticket ID reference
+  Skip this record update
+  Skip all updates that require a Ticket ID
+```
+
+#### Ticket suggestions
+
+When `TicketSuggestionOutput` is configured in `.dbo/config.json` (set during `dbo init`), the CLI automatically fetches relevant ticket suggestions from the server and presents them as selectable choices:
+
+```
+? Select a Ticket ID:
+❯ 1 (TKT-001): Fix login page [login-fix]
+  2 (TKT-002): Update dashboard [dashboard-v2]
+  3 (TKT-003): Refactor auth [auth-refactor]
+  Enter a Ticket ID manually…
+```
+
+The suggestions are fetched from the configured output endpoint, filtered by the current record's UID. Users can arrow-key through the list to select a ticket, or choose "Enter a Ticket ID manually" for custom input.
+
+If `TicketSuggestionOutput` is not configured or the fetch fails, the CLI falls back to a plain text input prompt.
+
+When the server returns a `repo_mismatch` (Ticket ID belongs to a different repository), the CLI prompts:
+
+```
+⚠ Ticket "TICKET-123" is for another repository.
+? The Ticket ID of "TICKET-123" is for another Repository:
+❯ Commit anyway
+  Submit with another Ticket ID
+  Skip this record
+  Commit all transactions with this ID anyway
+  Commit all transactions with another Ticket ID, and update my current Ticket ID reference
+  Skip all
+```
+
+Ticket selections are stored in `.dbo/ticketing.local.json` for reuse across submissions. Per-record tickets are cleaned up after successful submission; the global ticket persists until explicitly cleared. The `--ticket` flag always takes precedence over stored tickets.
+
+#### Ticket ID required (legacy)
+
+When the server returns `ticket_lookup_required_error`, the CLI prompts:
+
+```
+⚠ This operation requires a Ticket ID.
+? Ticket ID Required: ___
+```
+
+The submission is then retried with `_OverrideTicketID`. To skip the prompt, pass `--ticket <id>` upfront.
+
+#### Pre-submission ticket prompt
+
+When a stored ticket exists in `.dbo/ticketing.local.json`, the CLI prompts before batch submissions (`push`, `input`, `add`, `content deploy`, `deploy`):
+
+```
+? Use stored Ticket ID "TICKET-123" for this submission?
+❯ Yes, use "TICKET-123"
+  Use a different ticket for this submission only
+  Use a different ticket for this and future submissions
+  No, clear stored ticket
+  Cancel submission
+```
+
+- **Yes** — applies the stored ticket to all records in this submission
+- **Different ticket (this submission only)** — prompts for a ticket ID, uses it for all records in this invocation without updating `ticketing.local.json`
+- **Different ticket (this and future)** — prompts for a ticket ID, updates `ticketing.local.json`, and uses it for this and all future submissions
+- **No, clear** — removes the stored `ticket_id` and proceeds without a ticket
+- **Cancel** — aborts the submission
+
+#### `.dbo/ticketing.local.json`
+
+Stores ticket IDs for automatic application during submissions:
+
+```json
+{
+  "ticket_id": "TICKET-123",
+  "records": [
+    {
+      "UID": "a2dxvg23rk6xsmnum7pdxa",
+      "RowID": 16012,
+      "entity": "content",
+      "ticket_id": "TICKET-456",
+      "expression": "RowID:16012;column:content._LastUpdatedTicketID=TICKET-456"
+    }
+  ]
+}
+```
+
+- `ticket_id` — Global ticket applied to all submissions until cleared
+- `records` — Per-record tickets (auto-cleared after successful submission)
+- `--ticket` flag always takes precedence over stored tickets
+
+#### ModifyKey protection (locked/production apps)
+
+When an app has a `ModifyKey` set (production/locked mode), the CLI guards all submission commands (`push`, `input`, `add`, `content deploy`, `deploy`) with an interactive prompt:
+
+```
+⚠  This app is locked (production mode). A ModifyKey is required to submit changes.
+? This app has a ModifyKey set. How would you like to proceed?
+❯ Enter the ModifyKey to proceed
+  Cancel submission
+```
+
+The ModifyKey is detected and stored during `dbo clone`. If the key wasn't stored locally but the server requires one, the CLI reactively prompts after the first failed submission:
+
+```
+⚠  This app requires a ModifyKey. The key has not been set locally (try re-running `dbo clone`).
+? A ModifyKey is required. How would you like to proceed?
+❯ Enter the ModifyKey to retry
+  Cancel submission
+```
+
+On successful reactive entry, the key is saved to `.dbo/config.json` for future use.
+
+To bypass the interactive prompt entirely, pass `--modify-key <key>` on any submission command:
+
+```bash
+dbo push . --modify-key mySecretKey
+dbo input -d '...' --modify-key mySecretKey
+dbo add myfile.css --modify-key mySecretKey
+```
+
+#### User identity required
+
+When the server returns an error mentioning `LoggedInUser_UID`, `LoggedInUserID`, `CurrentUserID`, or `UserID`, the CLI checks for a stored user identity from `dbo login`:
+
+```
+⚠ This operation requires an authenticated user (LoggedInUser_UID).
+  Your session may have expired, or you may not be logged in.
+  You can log in with "dbo login" to avoid this prompt in the future.
+  Stored session user UID: albain3dwkofbhnd1qtd1q
+? User UID Required:
+❯ Use session user (UID: albain3dwkofbhnd1qtd1q)
+  Enter a different User UID
+```
+
+If no stored user info is available, it prompts for direct input. The CLI automatically determines whether the server needs a UID or numeric ID based on the error message pattern.
+
+---
+
+### `dbo install` (alias: `dbo i`)
+
+Install or upgrade dbo cli components including the CLI itself, plugins, and Claude Code integration.
+
+```bash
+# Interactive — choose what to install
+dbo install
+
+# Install/upgrade CLI from npm (latest)
+dbo i dbo
+dbo i dbo@latest
+
+# Install a specific CLI version
+dbo i dbo@0.4.1
+
+# Install CLI from local source directory
+dbo install /path/to/local/cli/src
+
+# Install/upgrade Claude Code commands
+dbo install plugins
+dbo install claudecommands
+
+# Install Claude Code commands globally (shared across projects)
+dbo install plugins --global
+
+# Explicitly install to project directory
+dbo install plugins --local
+
+# Install Claude Code CLI (if not present) + commands
+dbo install claudecode
+
+# Install/upgrade a specific command plugin
+dbo install --claudecommand dbo
+
+# Install a specific command globally
+dbo install --claudecommand dbo --global
+```
+
+| Flag | Description |
+|------|-------------|
+| `[target]` | What to install: `dbo[@version]`, `plugins`, `claudecommands`, `claudecode`, or a local path |
+| `--claudecommand <name>` | Install/upgrade a specific command by name |
+| `-g, --global` | Install commands to user home directory (`~/.claude/commands/`) |
+| `--local` | Install commands to project directory (`.claude/commands/`) |
+
+Smart behavior:
+- If the CLI is already installed, prompts to upgrade (with version comparison)
+- If plugins are already installed and up to date, reports "already up to date"
+- If plugins differ from source, prompts to upgrade to the latest version
+- Compares file hashes — unchanged files are skipped
+- Adds project-scoped plugins to `.gitignore` (source of truth is `plugins/claude/` at repo root)
+- Per-plugin scope (project or global) is stored in `.dbo/config.local.json` and remembered for future upgrades
+- On re-install (e.g. after `npm install` or `npm link`), scope is inferred automatically from the global plugin registry (`~/.claude/plugins/installed_plugins.json`) or existing project installation — no prompt is shown
+- On first install with no prior preference and no existing installation, prompts for scope
+- `--global` / `--local` flags override stored preferences and update them
+
+---
+
+### `dbo deploy`
+
+Deploy files to DBO.io using a `.dbo/deploy_config.json` manifest or direct arguments.
+
+```bash
+# Deploy a named entry from the manifest
+dbo deploy css:colors
+
+# Deploy all entries
+dbo deploy --all
+
+# Deploy with ticket ID
+dbo deploy js:app --ticket abc123
+
+# Validate without deploying
+dbo deploy css:colors --confirm false
+
+# Deploy a multipart (binary) entry from manifest
+dbo deploy img:logo
+```
+
+| Flag | Description |
+|------|-------------|
+| `<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 |
+| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
+| `--row-key <type>` | Override row key type for this invocation (`RowUID` or `RowID`) |
+| `--json` | Output raw JSON |
+| `-v, --verbose` | Show HTTP request details |
+| `--domain <host>` | Override domain |
+
+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_config.json` manifest
+
+Create a `.dbo/deploy_config.json` file to define named deployments:
+
+```json
+{
+  "deployments": {
+    "css:colors": {
+      "uid": "albain3dwkofbhnd1qtd1q",
+      "file": "assets/css/colors.css"
+    },
+    "js:app": {
+      "uid": "rncjivlghu65bmkbjnxynq",
+      "file": "assets/js/app.js"
+    },
+    "doc:colors": {
+      "uid": "l2uv2gu8gu6ziyluuncv0w",
+      "file": "docs/colors.md",
+      "entity": "extension",
+      "column": "Text"
+    },
+    "img:logo": {
+      "uid": "x9fk2m3npqrs7tuvwyz1ab",
+      "file": "assets/images/logo.png",
+      "multipart": true
+    },
+    "upload:icons": {
+      "uid": "7ddf10982a96457fa4f440",
+      "file": "assets/css/launchpad-icons.css",
+      "multipart": true,
+      "filename": "launchpad-icons.css"
+    }
+  }
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `uid` | Target record UID (required) | — |
+| `file` | Local file path (required) | — |
+| `entity` | Target entity name | `content` (`media` when `multipart: true`) |
+| `column` | Target column name | `Content` (`File` when `multipart: true`) |
+| `multipart` | Use multipart/form-data upload (for binary files) | `false` |
+| `filename` | Set the `Filename` column on the target record | basename of `file` |
+
+This replaces the curl commands typically embedded in `package.json` scripts.
+
+#### Automatic deploy config generation
+
+When you run `dbo clone` or `dbo add`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.dbo/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
+
+```bash
+dbo clone   # → .dbo/deploy_config.json auto-populated with one entry per companion file
+```
+
+Keys are derived as `<extension>:<basename>` from the companion file path. If two files share the same key, a parent directory segment is appended to disambiguate (`css:colors` and `css:admin/colors`). Entries include `entity` and `column` from the record metadata.
+
+Once generated, you can deploy by name or by UID:
+
+```bash
+dbo deploy css:colors                   # deploy by key name
+dbo deploy cdlftyk2lkg21whojzqqoa       # deploy by UID (scans manifest values)
+```
+
+Entries are updated automatically on re-clone (path changes are reflected in place) and removed when you run `dbo rm`. When you `dbo mv` a file, the old entry is removed and a new entry is inserted with the correct key for the new path.
+
+#### Non-interactive mode (npm scripts)
+
+When running `dbo deploy` (or any submission command) inside npm scripts or piped commands where stdin is not a TTY, the CLI automatically skips all interactive prompts and uses stored credentials:
+
+- **Stored ticket** — auto-applied from `.dbo/ticketing.local.json`
+- **ModifyKey** — auto-applied from `.dbo/config.json` (`AppModifyKey`)
+- **User identity** — auto-applied from `.dbo/credentials.json`
+
+If a required value is missing and no interactive prompt is possible, the command fails with a clear error message explaining how to set up the missing value.
+
+Example `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "deploy:css": "dbo deploy css:colors && dbo deploy css:layout",
+    "deploy:docs": "dbo deploy doc:readme && dbo deploy doc:api",
+    "deploy:all": "dbo deploy --all"
+  }
+}
+```
+
+To set up for non-interactive use:
+1. Run `dbo login` to store user credentials
+2. Run `dbo clone` to store the ModifyKey (if applicable)
+3. Set a ticket interactively once — it persists in `ticketing.local.json` for future npm script runs
+
+---
+
+## Script Hooks
+
+Script hooks let you define build and push lifecycle commands in `.dbo/scripts.json`. Hooks run automatically during `dbo push` and can also be triggered independently with `dbo build` and `dbo run`.
+
+### Configuration Files
+
+| File | Tracked | Purpose |
+|------|---------|---------|
+| `.dbo/scripts.json` | Yes | Shared hook definitions (committed to git) |
+| `.dbo/scripts.local.json` | No | Per-user overrides (gitignored) |
+
+### Top-level Keys
+
+| Key | Description |
+|-----|-------------|
+| `scripts` | Global hooks and named scripts (apply to all targets) |
+| `targets` | Per-file or per-directory hooks (highest priority) |
+| `entities` | Per-entity-type hooks (e.g., `content`, `extension.control`) |
+
+### Example `.dbo/scripts.json`
+
+```json
+{
+  "scripts": {
+    "prepush": "echo pushing $DBO_TARGET"
+  },
+  "targets": {
+    "lib/bins/app/assets/js/operator.js": {
+      "build": "rollup -c src/rollup_config.mjs",
+      "push": false
+    }
+  },
+  "entities": {
+    "extension.control": {
+      "prebuild": "npm run compile-controls"
+    }
+  }
+}
+```
+
+### Lifecycle Hooks
+
+| Hook | Phase | Description |
+|------|-------|-------------|
+| `prebuild` | Build | Runs before build |
+| `build` | Build | Main build step |
+| `postbuild` | Build | Runs after build |
+| `prepush` | Push | Runs before push |
+| `push` | Push | Custom push (replaces default HTTP submit) |
+| `postpush` | Push | Runs after push |
+
+### Resolution Order
+
+Hooks resolve per-hook from lowest to highest priority:
+
+1. **Global** (`scripts`) — applies to all targets
+2. **Entity** (`entities`) — applies to targets matching the entity type
+3. **Target** (`targets`) — applies to a specific file or directory
+
+A target can override `build` while the global `prepush` still applies.
+
+### Hook Value Types
+
+| Value | Behavior |
+|-------|----------|
+| `"command"` | Run as shell command |
+| `["cmd1", "cmd2"]` | Run sequentially; fail-fast on first non-zero exit |
+| `false` | Skip (for `push`: skip HTTP submit) |
+| `true` / omitted | Use default behavior |
+
+### Environment Variables
+
+These env vars are injected into all hook processes:
+
+| Variable | Description |
+|----------|-------------|
+| `DBO_TARGET` | Relative file path being processed |
+| `DBO_ENTITY` | Entity type (e.g., `content`, `extension`) |
+| `DBO_DOMAIN` | Configured domain |
+| `DBO_APP` | App short name |
+| `DBO_APP_UID` | App UID |
+
+### Push Flags
+
+| Flag | Description |
+|------|-------------|
+| `--no-scripts` | Bypass all script hooks; run default push pipeline |
+| `--no-build` | Skip build phase; run push phase only |
+
+### `dbo build [path]`
+
+Runs the build lifecycle (`prebuild` → `build` → `postbuild`) without pushing.
+
+```bash
+# Build a specific target
+dbo build lib/bins/app/assets/js/operator.js
+
+# Build all targets with a build hook
+dbo build
+```
+
+### `dbo run [script-name]`
+
+Runs a named global script from `.dbo/scripts.json` (like `npm run`). Automatically runs `pre<name>` and `post<name>` scripts if defined.
+
+```bash
+# List all available scripts
+dbo run
+
+# Run a specific script
+dbo run prepush
+```
+
+---
+
+## Global Flags
+
+These flags are available on most commands:
+
+| Flag | Description |
+|------|-------------|
+| `-C, --confirm <true\|false>` | Commit changes (default: `true`). Use `false` for validation only |
+| `--json` | Output raw JSON response with syntax highlighting |
+| `--jq <expr>` | Filter JSON response with a jq-like expression (implies `--json`) |
+| `-v, --verbose` | Show HTTP request details (method, URL, body) |
+| `--domain <host>` | Override the configured domain for this request |
+| `-h, --help` | Show help for any command |
+
+---
+
+## JSON Filtering (`--jq`)
+
+The `--jq` flag provides built-in jq-like JSON filtering without requiring `jq` to be installed. It supports the most common patterns:
+
+```bash
+# Pretty-print the entire response (with syntax highlighting)
+dbo output -e user --jq '.'
+
+# Extract a specific key
+dbo output -e user --jq '.Payload'
+
+# Nested key access
+dbo input -d '...' --jq '.Payload.Results.Add'
+
+# Pluck a field from every item in an array
+dbo output -e user --jq '.Payload.Results.Add[].UID'
+
+# Array index
+dbo output -e user --jq '.Payload.Results.Add[0]'
+
+# Pipe: iterate then access
+dbo output -e user --jq '.Payload.Results.Add[] | .UID'
+
+# Use with any command that returns JSON
+dbo cache list --jq '.Payload'
+dbo message myUID --jq '.Successful'
+```
+
+### Supported expressions
+
+| Expression | Description |
+|-----------|-------------|
+| `.` | Identity (entire response) |
+| `.key` | Access a top-level key |
+| `.key.nested` | Nested key access |
+| `.[0]` | Array index |
+| `.[]` | Iterate array |
+| `.[].field` | Pluck field from each array item |
+| `.[] \| .field` | Pipe: iterate then access |
+| `.["key.name"]` | Bracket notation for keys with dots |
+
+When `--jq` is used, the API request is automatically made with `_template=json_raw`.
+
+### JSON syntax highlighting
+
+Both `--json` and `--jq` output use syntax highlighting:
+- **Keys** in cyan
+- **Strings** in green
+- **Numbers** in yellow
+- **Booleans/null** in magenta
+
+---
+
+## DBO API Parameter Reference
+
+The DBO.io API uses a token architecture for dynamic parameters. All parameters are passed as URL query string key-value pairs.
+
+### Token Syntax
+
+Parameters follow the token delimiter system:
+
+```
+_tokenType@reference$target!defaultValue:modifier=value
+```
+
+| Delimiter | Purpose | Example |
+|-----------|---------|---------|
+| `_` | Prefix for token type | `_filter`, `_sort`, `_limit` |
+| `@` | Reference (column, field, key) | `_filter@FirstName=John` |
+| `$` | Target (scope to a specific output/entity) | `_limit$outputUid=100` |
+| `!` | Default value (fallback) | `_filter@Status!active=value` |
+| `:` | Modifier(s) | `_filter@Name:Contains=john` |
+
+### Output Parameters
+
+These parameters control the output endpoint behavior (`/api/output/{uid}` and `/api/output/entity/{entityUid}`):
+
+#### Filtering
+
+```
+_filter@ColumnName=value                          # exact match (default)
+_filter@ColumnName:Contains=value                 # LIKE %value%
+_filter@ColumnName:StartsWith=value               # LIKE value%
+_filter@ColumnName:EndsWith=value                 # LIKE %value
+_filter@ColumnName:LessThan=value                 # < comparison
+_filter@ColumnName:LessThanOrEqualTo=value        # <= comparison
+_filter@ColumnName:GreaterThan=value              # > comparison
+_filter@ColumnName:GreaterThanOrEqualTo=value     # >= comparison
+_filter@ColumnName:Contains,And=value             # AND logic (default is OR)
+_filter@ColumnName:Contains,Exclude=value         # NOT LIKE
+_filter$outputTarget@ColumnName=value             # scoped to specific output
+```
+
+#### Sorting
+
+```
+_sort=ColumnName                                  # ascending (default)
+_sort=ColumnName:ASC                              # explicit ascending
+_sort=ColumnName:DESC                             # descending
+_sort=Column1:ASC,Column2:DESC                    # multiple sorts (comma-separated)
+_sort=ColumnName ASC                              # space-separated also works
+```
+
+Multiple `_sort` parameters can be specified; earlier sorts take precedence.
+
+#### Pagination
+
+```
+_limit=30                                         # max 30 rows
+_limit=10-30                                      # rows 10 through 30 (range)
+_limit=10&_page=3                                 # 10 rows per page, page 3
+_rowcount=false                                   # disable row count for performance
+```
+
+Deprecated (still accepted): `_maxrows`, `_rows`, `_rowsperpage`
+
+#### Search
+
+```
+_search=keyword                                   # full-text search across searchable columns
+_search@ColumnName=keyword                        # search specific column
+```
+
+#### Template & Format
+
+```
+_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
+_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
+
+```
+_display@tagName=show                             # show a template content tag
+_display@tagName=hide                             # hide a template content tag
+_empty_response_code=404                          # HTTP status when results are empty
+_fallback_content:404=contentUID                  # render a different content on 404
+```
+
+#### Debug & Profiling
+
+```
+_debug=true                                       # general debug output
+_debug:sql=true                                   # return SQL without executing
+_debug:verbose=true                               # verbose debug
+_debug:analysis=true                              # analysis debug
+_profile=true                                     # MiniProfiler output
+```
+
+Other debug sub-keys: `http_modules`, `instance`, `rewrites`, `cache`, `executable_contents`, `security`, `controllers`, `embeds`, `includes`, `contents`, `template_render`, `tokens`, `messages`, `media`, `request_stack`, `query_execution`, `query_building`
+
+#### Control Flags
+
+```
+_strict=true                                      # strict error mode
+_confirm=true                                     # confirmation flag for operations
+_no_transaction=true                              # disable transaction wrapping
+_skip=all                                         # skip execution phases (admin-only)
+_include=value                                    # include token
+_security=value                                   # security filter enforcement
+```
+
+### Data Tokens (used in templates)
+
+| Token | Description |
+|-------|-------------|
+| `#{value@ColumnName}` | Column value from output row |
+| `#{id}` | Row primary key |
+| `#{uid}` | Row UID |
+| `#{CurrentUser@field}` | Current user field (e.g., `FirstName`, `Email`) |
+| `#{request@key}` | URL parameter value |
+| `#{session@variable}` | Session variable |
+| `#{site@field}` | Site field |
+| `#{date:format}` | Current date/time |
+| `#{unique:uid}` | Generate unique UID |
+| `#{count}` | Row count |
+| `#{page}` | Current page number |
+
+### Template Tags
+
+System tags (used in output templates):
+
+| Tag | Purpose |
+|-----|---------|
+| `<#_row>` | Row template |
+| `<#_header>` | Header template |
+| `<#_footer>` | Footer template |
+| `<#_cell>` | Cell template |
+| `<#_empty>` | Empty result template |
+| `<#_noresult>` | No result template |
+| `<#_prompt>` | Prompt template |
+| `<#_shared>` | Shared template |
+| `<#_rowdelimiter>` | Row delimiter |
+| `<#_celldelimiter>` | Cell delimiter |
+| `<#_value>` | Value template |
+| `<#_embed url="...">` | Embed nested content/output |
+
+User-defined tags use `<#reference>` (no underscore prefix).
+
+---
+
+## Migration from curl
+
+The `dbo` CLI is a drop-in replacement for the curl-based workflow. Here's how common operations translate:
+
+### Authentication
+
+**Before:**
+```bash
+echo "my-domain.com" > .domain
+echo "user@example.com" > .username
+echo "mypassword" > .password
+curl --cookie-jar .cookies -K authenticate.curl
+```
+
+**After:**
+```bash
+dbo init --domain my-domain.com --username user@example.com
+dbo login
+```
+
+### Edit a record
+
+**Before:**
+```bash
+curl -K config-data.curl -d "RowID:10065;column:user.FirstName=Jane"
+```
+
+**After:**
+```bash
+dbo input -d 'RowID:10065;column:user.FirstName=Jane'
+```
+
+### Deploy CSS from a local file
+
+**Before:**
+```bash
+curl -K config-data.curl --data-urlencode RowUID%3Aalbain3dwkofbhnd1qtd1q%3Bcolumn%3Acontent.Content@assets/css/colors.css
+```
+
+**After:**
+```bash
+dbo content deploy albain3dwkofbhnd1qtd1q assets/css/colors.css
+```
+
+### Upload a media file
+
+**Before:**
+```bash
+curl -K config-form.curl -F file=@path/to/image.jpg -F "RowID:add1;column:media.BinID=12345" -F "RowID:add1;column:media.AppID=67890" -F "RowID:add1;column:media.Ownership=app" -F "RowID:add1;column:media.Path=assets/images"
+```
+
+**After:**
+```bash
+dbo upload image.jpg --bin 12345 --app 67890 --ownership app --path assets/images
+```
+
+### Query data
+
+**Before:**
+```bash
+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' --template json_indented
+```
+
+### Cookie compatibility
+
+The `dbo` CLI writes cookies in Netscape format (same as curl's `--cookie-jar`). You can use the same cookie file with both tools during migration:
+
+```bash
+dbo login
+curl -b .dbo/cookies.txt https://my-domain.com/api/content/myUID
+```
+
+---
+
+## License
+
+Copyright manolab, LLC