@dboio/cli 0.16.2 → 0.17.0

package/README.md

@@ -233,7 +233,7 @@ Use `dbo status` to see how many pending migrations exist.
 | 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`) |
+| `AppID` | number | App ID (set by `dbo clone`, used by `dbo adopt`/`dbo input`) |
 | `AppUID` | string | App UID |
 | `AppName` | string | App display name |
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
@@ -305,7 +305,7 @@ A gitignore-style file in the project root that controls which files and directo
 
 **Used by:**
 - `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
-- `dbo add .` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo add file.html`)
+- `dbo adopt ./` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo adopt 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.
@@ -591,7 +591,7 @@ dbo clone -e extension                               # Clone all extensions (all
 dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
 ```
 
-**`dbo add` auto-inference**: Running `dbo add docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `extension/documentation/` with the correct `@/` reference.
+**`dbo adopt` auto-inference**: Running `dbo adopt docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `lib/extension/documentation/` with the correct `@/` reference.
 
 #### Output structure
 
@@ -749,11 +749,11 @@ During `dbo clone`, the CLI auto-generates `.dbo/metadata_schema.json` (formerly
 | `String10=@reference` | Content reference — links to the file being added |
 | `String5=@reference:@Name[js]` | Content reference with filename source and extension |
 
-`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 adopt` uses these templates to auto-detect the entity type from a file's directory placement and generate metadata without prompting. For example, `dbo adopt lib/extension/include/nav.html` resolves to entity `extension` / descriptor `include` and applies the matching template.
 
 #### `@reference` expression syntax
 
-The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo add`. The full grammar:
+The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo adopt`. The full grammar:
 
 ```
 Column=@reference[:filenameSource][extPart][{title}]
@@ -1407,7 +1407,7 @@ Apply macOS Finder color tags or Linux gio emblems to companion files based on t
 |-----|-------|---------|
 | `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:Untracked` | 🟡 Yellow | No metadata — not yet adopted with `dbo adopt` |
 | `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
 
 ```bash
@@ -1507,73 +1507,87 @@ The next `dbo push` processes all pending deletions before pushing file changes.
 
 ---
 
-### `dbo add`
+### `dbo adopt`
 
-Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
+Create a metadata companion file for a local file, making it ready for server insertion on the next `dbo push`. This is a **local-only operation** — no server requests are made.
 
-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.
+Files matching `.dboignore` patterns are skipped — both in directory mode (`dbo adopt ./`) and single-file mode (`dbo adopt 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
+# Single file — entity inferred from directory
+dbo adopt lib/bins/app/assets/css/colors.css
 
-# Add with auto-accept prompts
-dbo add assets/css/colors.css -y
+# Single file — explicit entity
+dbo adopt lib/bins/app/assets/css/colors.css -e content
 
-# Add with ticket ID
-dbo add assets/css/colors.css --ticket abc123
+# Extension with explicit column
+dbo adopt lib/extension/widget/button.html -e extension.String5
+
+# Skip all confirmation prompts
+dbo adopt lib/bins/app/assets/css/colors.css -e content -y
 ```
 
-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.
+If the file lives in a recognized directory (e.g. `lib/bins/`, `lib/extension/`, `docs/`), the entity is auto-inferred via `resolveDirective()`. Otherwise, pass `-e <entity>` or follow the interactive wizard.
 
-#### Directory scan
+#### Attach to existing record (`--into`)
 
 ```bash
-# Scan current directory for un-added files
-dbo add .
-
-# Scan a specific directory
-dbo add assets/
+# Attach a second file to the same record
+dbo adopt file2.css --into file1.metadata.json -e String6
 ```
 
-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
+Adds `String6: "@file2.css"` to `file1.metadata.json` and appends `String6` to `_companionReferenceColumns`. No separate `file2.metadata.json` is created. Requires `-e <column>`.
 
-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:
+#### Directory mode
 
 ```bash
-dbo pull -e content <uid>
+# Adopt all untracked media files in a directory
+dbo adopt lib/bins/app/assets/img/ -e media
+
+# Adopt all untracked files in the entire project as media
+dbo adopt . -e media -y
 ```
 
-#### Metadata generated by add
+Recursively finds files that have no `.metadata.json` companion (or have metadata without a UID/`_CreatedOn`). Lists them and prompts for confirmation before creating metadata. The `-e` flag is required in directory mode.
+
+#### After adopting
+
+After `dbo adopt`, run `dbo push` to insert the new record(s) on the server. Push detects metadata files without a UID and submits them as new inserts.
 
-Minimal (no optional fields provided):
+#### Metadata generated by adopt
+
+Content entity (auto-detected from `lib/bins/`):
 ```json
 {
+  "_entity": "content",
+  "_companionReferenceColumns": ["Content"],
   "Name": "colors",
-  "Path": "assets/css/colors.css",
   "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Extension": "CSS",
+  "Path": "assets/css/colors.css",
+  "Active": 1,
+  "Public": 0,
+  "BinID": 11045,
+  "AppID": 10100
 }
 ```
 
-With optional fields (only included if the user provides values during the wizard):
+Media entity:
 ```json
 {
+  "_entity": "media",
+  "_mediaFile": "@logo.png",
+  "Name": "logo",
+  "Filename": "logo.png",
+  "Extension": "png",
+  "Ownership": "App",
+  "BinID": 11048,
   "AppID": 10100,
-  "BinID": 11045,
-  "SiteID": 10061,
-  "Name": "colors",
-  "Path": "assets/css/colors.css",
-  "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Path": "assets/img",
+  "MimeType": "image/png",
+  "FullPath": "/media/myapp/app/assets/img/logo.png"
 }
 ```
 
@@ -1581,18 +1595,15 @@ The `@colors.css` reference tells the CLI to read the file content from `colors.
 
 | 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 |
+| `<path>` | File path, directory path, or `.` for current directory |
+| `-e, --entity <spec>` | Entity and optional column: `content`, `media`, `extension.widget`, `extension.String5`. Required in directory mode. |
+| `--into <metaPath>` | Attach file to an existing metadata record as an additional companion column (single-file only) |
+| `-y, --yes` | Skip all confirmation prompts |
+| `--domain <host>` | Override domain |
 
 #### Column filtering
 
-The `add` and `push` commands never submit these server-managed columns:
+The `push` command never submits these server-managed columns (applies to records created by `adopt`):
 - `_CreatedOn`, `_LastUpdated` — set by the server
 - `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
 - `UID` — assigned by the server on insert
@@ -1602,7 +1613,7 @@ The `add` and `push` commands never submit these server-managed columns:
 
 ### Automatic error recovery
 
-The `input`, `push`, and `add` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
+The `input` and `push` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
 
 #### Ticket error recovery
 
@@ -1728,7 +1739,7 @@ To bypass the interactive prompt entirely, pass `--modify-key <key>` on any subm
 ```bash
 dbo push . --modify-key mySecretKey
 dbo input -d '...' --modify-key mySecretKey
-dbo add myfile.css --modify-key mySecretKey
+dbo push myfile.css --modify-key mySecretKey
 ```
 
 #### User identity required
@@ -1891,7 +1902,7 @@ 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:
+When you run `dbo clone` or `dbo adopt`, 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

package/bin/dbo.js

@@ -24,7 +24,7 @@ import { instanceCommand } from '../src/commands/instance.js';
 import { deployCommand } from '../src/commands/deploy.js';
 import { pushCommand } from '../src/commands/push.js';
 import { pullCommand } from '../src/commands/pull.js';
-import { addCommand } from '../src/commands/add.js';
+import { adoptCommand } from '../src/commands/adopt.js';
 import { installCommand } from '../src/commands/install.js';
 import { cloneCommand } from '../src/commands/clone.js';
 import { diffCommand } from '../src/commands/diff.js';
@@ -87,7 +87,7 @@ program.addCommand(instanceCommand);
 program.addCommand(deployCommand);
 program.addCommand(pushCommand);
 program.addCommand(pullCommand);
-program.addCommand(addCommand);
+program.addCommand(adoptCommand);
 program.addCommand(installCommand);
 program.addCommand(cloneCommand);
 program.addCommand(diffCommand);

package/package.json

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

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

@@ -233,7 +233,7 @@ Use `dbo status` to see how many pending migrations exist.
 | 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`) |
+| `AppID` | number | App ID (set by `dbo clone`, used by `dbo adopt`/`dbo input`) |
 | `AppUID` | string | App UID |
 | `AppName` | string | App display name |
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
@@ -305,7 +305,7 @@ A gitignore-style file in the project root that controls which files and directo
 
 **Used by:**
 - `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
-- `dbo add .` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo add file.html`)
+- `dbo adopt ./` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo adopt 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.
@@ -591,7 +591,7 @@ dbo clone -e extension                               # Clone all extensions (all
 dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
 ```
 
-**`dbo add` auto-inference**: Running `dbo add docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `extension/documentation/` with the correct `@/` reference.
+**`dbo adopt` auto-inference**: Running `dbo adopt docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `lib/extension/documentation/` with the correct `@/` reference.
 
 #### Output structure
 
@@ -749,11 +749,11 @@ During `dbo clone`, the CLI auto-generates `.dbo/metadata_schema.json` (formerly
 | `String10=@reference` | Content reference — links to the file being added |
 | `String5=@reference:@Name[js]` | Content reference with filename source and extension |
 
-`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 adopt` uses these templates to auto-detect the entity type from a file's directory placement and generate metadata without prompting. For example, `dbo adopt lib/extension/include/nav.html` resolves to entity `extension` / descriptor `include` and applies the matching template.
 
 #### `@reference` expression syntax
 
-The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo add`. The full grammar:
+The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo adopt`. The full grammar:
 
 ```
 Column=@reference[:filenameSource][extPart][{title}]
@@ -1407,7 +1407,7 @@ Apply macOS Finder color tags or Linux gio emblems to companion files based on t
 |-----|-------|---------|
 | `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:Untracked` | 🟡 Yellow | No metadata — not yet adopted with `dbo adopt` |
 | `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
 
 ```bash
@@ -1507,73 +1507,87 @@ The next `dbo push` processes all pending deletions before pushing file changes.
 
 ---
 
-### `dbo add`
+### `dbo adopt`
 
-Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
+Create a metadata companion file for a local file, making it ready for server insertion on the next `dbo push`. This is a **local-only operation** — no server requests are made.
 
-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.
+Files matching `.dboignore` patterns are skipped — both in directory mode (`dbo adopt ./`) and single-file mode (`dbo adopt 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
+# Single file — entity inferred from directory
+dbo adopt lib/bins/app/assets/css/colors.css
 
-# Add with auto-accept prompts
-dbo add assets/css/colors.css -y
+# Single file — explicit entity
+dbo adopt lib/bins/app/assets/css/colors.css -e content
 
-# Add with ticket ID
-dbo add assets/css/colors.css --ticket abc123
+# Extension with explicit column
+dbo adopt lib/extension/widget/button.html -e extension.String5
+
+# Skip all confirmation prompts
+dbo adopt lib/bins/app/assets/css/colors.css -e content -y
 ```
 
-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.
+If the file lives in a recognized directory (e.g. `lib/bins/`, `lib/extension/`, `docs/`), the entity is auto-inferred via `resolveDirective()`. Otherwise, pass `-e <entity>` or follow the interactive wizard.
 
-#### Directory scan
+#### Attach to existing record (`--into`)
 
 ```bash
-# Scan current directory for un-added files
-dbo add .
-
-# Scan a specific directory
-dbo add assets/
+# Attach a second file to the same record
+dbo adopt file2.css --into file1.metadata.json -e String6
 ```
 
-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
+Adds `String6: "@file2.css"` to `file1.metadata.json` and appends `String6` to `_companionReferenceColumns`. No separate `file2.metadata.json` is created. Requires `-e <column>`.
 
-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:
+#### Directory mode
 
 ```bash
-dbo pull -e content <uid>
+# Adopt all untracked media files in a directory
+dbo adopt lib/bins/app/assets/img/ -e media
+
+# Adopt all untracked files in the entire project as media
+dbo adopt . -e media -y
 ```
 
-#### Metadata generated by add
+Recursively finds files that have no `.metadata.json` companion (or have metadata without a UID/`_CreatedOn`). Lists them and prompts for confirmation before creating metadata. The `-e` flag is required in directory mode.
+
+#### After adopting
+
+After `dbo adopt`, run `dbo push` to insert the new record(s) on the server. Push detects metadata files without a UID and submits them as new inserts.
 
-Minimal (no optional fields provided):
+#### Metadata generated by adopt
+
+Content entity (auto-detected from `lib/bins/`):
 ```json
 {
+  "_entity": "content",
+  "_companionReferenceColumns": ["Content"],
   "Name": "colors",
-  "Path": "assets/css/colors.css",
   "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Extension": "CSS",
+  "Path": "assets/css/colors.css",
+  "Active": 1,
+  "Public": 0,
+  "BinID": 11045,
+  "AppID": 10100
 }
 ```
 
-With optional fields (only included if the user provides values during the wizard):
+Media entity:
 ```json
 {
+  "_entity": "media",
+  "_mediaFile": "@logo.png",
+  "Name": "logo",
+  "Filename": "logo.png",
+  "Extension": "png",
+  "Ownership": "App",
+  "BinID": 11048,
   "AppID": 10100,
-  "BinID": 11045,
-  "SiteID": 10061,
-  "Name": "colors",
-  "Path": "assets/css/colors.css",
-  "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Path": "assets/img",
+  "MimeType": "image/png",
+  "FullPath": "/media/myapp/app/assets/img/logo.png"
 }
 ```
 
@@ -1581,18 +1595,15 @@ The `@colors.css` reference tells the CLI to read the file content from `colors.
 
 | 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 |
+| `<path>` | File path, directory path, or `.` for current directory |
+| `-e, --entity <spec>` | Entity and optional column: `content`, `media`, `extension.widget`, `extension.String5`. Required in directory mode. |
+| `--into <metaPath>` | Attach file to an existing metadata record as an additional companion column (single-file only) |
+| `-y, --yes` | Skip all confirmation prompts |
+| `--domain <host>` | Override domain |
 
 #### Column filtering
 
-The `add` and `push` commands never submit these server-managed columns:
+The `push` command never submits these server-managed columns (applies to records created by `adopt`):
 - `_CreatedOn`, `_LastUpdated` — set by the server
 - `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
 - `UID` — assigned by the server on insert
@@ -1602,7 +1613,7 @@ The `add` and `push` commands never submit these server-managed columns:
 
 ### Automatic error recovery
 
-The `input`, `push`, and `add` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
+The `input` and `push` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
 
 #### Ticket error recovery
 
@@ -1728,7 +1739,7 @@ To bypass the interactive prompt entirely, pass `--modify-key <key>` on any subm
 ```bash
 dbo push . --modify-key mySecretKey
 dbo input -d '...' --modify-key mySecretKey
-dbo add myfile.css --modify-key mySecretKey
+dbo push myfile.css --modify-key mySecretKey
 ```
 
 #### User identity required
@@ -1891,7 +1902,7 @@ 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:
+When you run `dbo clone` or `dbo adopt`, 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