@dboio/cli 0.19.7 → 0.20.0

package/README.md

@@ -140,7 +140,6 @@ my-project/
 │   │   └── 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)
@@ -149,7 +148,7 @@ my-project/
 │   ├── integration/    # Integration entity records
 │   ├── security/       # Security policy records
 │   ├── security_column/ # Column-level security records
-│   ├── data_source/    # (created when data sources exist)
+│   ├── data_source/    # Data source configs + entity (table) definitions
 │   ├── group/          # (created when groups exist)
 │   ├── site/           # (created when sites exist)
 │   └── redirect/       # (created when redirects exist)
@@ -203,7 +202,9 @@ Per-user settings (plugin scopes, completed migrations) are stored globally in `
 
 > **Upgrading to 0.16.0+**: `metadata_templates.json` is renamed to `metadata_schema.json`. The `_contentColumns` field in metadata files is renamed to `_companionReferenceColumns`. Extension companion file prompts during `dbo clone` are replaced by automatic derivation from `descriptor_definition` `form-control-code` data. Migration 011 runs automatically on first use.
 
-> **Upgrading to 0.14.0+**: Metadata files now use `name.metadata~uid.json` instead of `name~uid.metadata.json`. Migration 008 automatically renames all metadata files.
+> **Upgrading to 0.19.0+**: Metadata filenames no longer include `~UID` (e.g. `colors.metadata.json` instead of `colors.metadata~uid.json`). The UID is stored inside the JSON. Migration 013 automatically renames all metadata files.
+
+> **Upgrading to 0.14.0+**: Metadata files previously used `name.metadata~uid.json` instead of `name~uid.metadata.json`. Migration 008 handles this rename automatically.
 
 > **Upgrading to 0.13.3+**: Entity and extension companion files no longer include `~UID` in the filename. Migration 007 automatically renames legacy files.
 
@@ -298,8 +299,11 @@ Certain files live at the **project root** (not inside `lib/`) but are still tra
 | `manifest.json` | content | Yes | [PWA web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) |
 | `CLAUDE.md` | content | No | Claude Code project instructions |
 | `README.md` | content | Yes | Project readme |
+| `package.json` | content | No | Node.js package metadata and scripts |
+| `.dboignore` | content | No | DBO CLI ignore patterns |
+| `.gitignore` | content | No | Git ignore patterns |
 
-**`dbo clone`** writes all three to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description).
+**`dbo clone`** writes all six to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description, `package.json` as a minimal stub). Matching works regardless of the server record's `BinID`: records are matched by name, `@`-reference, or `Path`, then relocated to the root — whether they live in `lib/bins/app/`, another bin, or have `BinID=null`. Records with `BinID=null` that aren't in the configured list are also promoted to the project root automatically.
 
 **`dbo push`** auto-creates the companion metadata in `lib/bins/app/` for any listed root file that exists locally but has no tracked metadata yet — no manual `dbo adopt` needed before the first push.
 
@@ -322,11 +326,11 @@ The list of root content files is stored in `.app/config.json` under `rootConten
 
 ```json
 {
-  "rootContentFiles": ["CLAUDE.md", "README.md", "manifest.json"]
+  "rootContentFiles": ["CLAUDE.md", "README.md", "manifest.json", "package.json", ".dboignore", ".gitignore"]
 }
 ```
 
-- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json"]`
+- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json", "package.json", ".dboignore", ".gitignore"]`
 - **`[]`, `false`, or `null`**: feature disabled — no root content files are auto-managed
 - **Custom list**: any filename can be added; metadata is derived from the file extension
 
@@ -424,7 +428,7 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `--clone` | Clone the app after initialization |
 | `-g, --global` | Install Claude commands globally (`~/.claude/commands/`) |
 | `--local` | Install Claude commands to project (`.claude/commands/`) |
-| `--scaffold` | Pre-create standard project directories (`app_version`, `automation`, `bins`, `data_source`, `docs`, `extension`, `group`, `integration`, `site`, `src`, `tests`, `trash`) |
+| `--scaffold` | Pre-create standard project directories (`app_version`, `automation`, `bins`, `data_source`, `docs`, `extension`, `group`, `integration`, `site`, `src`, `tests`, `trash`). Note: `data_source/` is always scaffolded and also holds `entity` (table definition) records |
 | `--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` |
@@ -490,7 +494,7 @@ The project's reference domain is stored in `.app/<shortName>.metadata.json._dom
 7. **Saves `.app/directories.json`** — maps BinIDs to directory paths for file placement
 8. **Writes content files** — decodes base64 content, creates `*.metadata.json` + content files in the correct bin directory. Filename columns and companion file extraction preferences are auto-applied with sensible defaults on first clone (use `--configure` to re-prompt)
 9. **Downloads media files** — classifies records into three scopes before downloading: `app` (`/media/<app>/app/...` or no FullPath — always downloaded), `user` (`/media/<app>/user/...` — opt-in, preference saved as `UserMedia` in `config.json`), and `foreign` (`/media/<other_app>/...` — silently skipped with stale metadata written). Fetches using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`. 404 errors create stale metadata to prevent re-prompting. Errors are logged to `.app/errors.log`
-10. **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/`)
+10. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `entity`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory. Note: `entity` (table definitions) shares `lib/data_source/` with `data_source` records rather than using a separate directory
 11. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
 12. **Saves `.app/<shortName>.metadata.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
 13. **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
@@ -584,13 +588,14 @@ Where do you want me to place filename.ext?
 
 #### 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 types that correspond to project directories (`extension`, `app_version`, `data_source`, `entity`, `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/` |
+| `entity` | `data_source/` (co-located with data source records) |
 | `site` | `site/` |
 | `group` | `group/` |
 | `integration` | `integration/` |
@@ -600,7 +605,7 @@ For each entity type, the CLI prompts to choose which column becomes the filenam
 
 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 `_companionReferenceColumns` array (legacy name: `_contentColumns`, supported for backward compatibility).
 
-**Companion file naming convention:** Only `.metadata.json` files carry the `~UID` suffix (e.g. `Add-Asst-Execute-Security.metadata~wxl6ivcwfkix3zgantszjg.json`). Companion content files use the natural base name without `~UID` (e.g. `Add-Asst-Execute-Security.String5.html`). When a `{title}` is defined in the `@reference` expression (see [Metadata Schema](#metadata-schema)), the title replaces the column name in the filename (e.g. `Add-Asst-Execute-Security.Add-Form-Parameters.js` instead of `Add-Asst-Execute-Security.String5.js`). If two records share the same name within a directory, the second gets a `-1` suffix. Migration 007 automatically renames legacy `~UID` companion files to the natural convention.
+**Companion file naming convention:** Metadata files use `name.metadata.json` (e.g. `Add-Asst-Execute-Security.metadata.json`). The UID is stored inside the JSON, not in the filename. Companion content files use the natural base name (e.g. `Add-Asst-Execute-Security.String5.html`). When a `{title}` is defined in the `@reference` expression (see [Metadata Schema](#metadata-schema)), the title replaces the column name in the filename (e.g. `Add-Asst-Execute-Security.Add-Form-Parameters.js` instead of `Add-Asst-Execute-Security.String5.js`). If two records share the same name within a directory, the second gets a `-1` suffix (e.g. `Add-Asst-Execute-Security-1.metadata.json`); content records have priority over output records for the unsuffixed slot.
 
 Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
@@ -644,7 +649,7 @@ dbo clone -e extension --descriptor-types false       # Flat layout (no descript
 
 #### Entity children embedding
 
-When a server entity record contains nested child records (e.g., `entity_column` records nested under `entity` parents), `dbo clone` embeds them inline in the parent's `.metadata~uid.json` file under a `children` key:
+When a server entity record contains nested child records (e.g., `entity_column` records nested under `entity` parents), `dbo clone` embeds them inline in the parent's `.metadata.json` file under a `children` key:
 
 ```json
 {
@@ -693,7 +698,8 @@ project/
   docs/                      # ← root-placed documentation MD files (optional)
     MyDoc.md
   data_source/
-    MySQL-Primary.metadata.json
+    MySQL-Primary.metadata.json    # _entity: "data_source"
+    Users.metadata.json            # _entity: "entity" (table defs co-locate here)
   site/
     MainSite.metadata.json
   # Media files placed by BinID into bins/ (alongside content)

package/bin/dbo.js

@@ -101,4 +101,9 @@ program.addCommand(tagCommand);
 // Show welcome message on first run
 checkFirstRun();
 
+// Show help (exit 0) when invoked with no arguments
+if (process.argv.length <= 2) {
+  program.help();
+}
+
 program.parse();

package/package.json

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

package/plugins/claude/dbo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbo",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"

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

@@ -1,7 +1,7 @@
 ---
 name: dbo
-description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — for data reads/writes and runtime queries, use the REST API via curl with .app/cookies.txt instead.
-allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo add:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(dbo build:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
+description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/adopt/rm/diff/build/deploy). NOT for direct API operations — for data reads/writes and runtime queries, use the REST API via curl with .app/cookies.txt instead.
+allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo adopt:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(dbo build:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
 user-invokable: true
 ---
 
@@ -12,7 +12,7 @@ Run `dbo` CLI commands for local file operations, project management, and deploy
 ## CLI vs REST API — When to use what
 
 **Use this CLI skill for file operations:**
-- `pull`, `push`, `add`, `clone`, `rm`, `diff` — sync files between local project and server
+- `pull`, `push`, `adopt`, `clone`, `rm`, `diff` — sync files between local project and server
 - `deploy` — push a file to DBO by UID or named shorthand (shorthands defined in `.app/deploy_config.json`)
 - `build`, `run` — compile source and run lifecycle scripts (configured in `.app/scripts.json`)
 - `init`, `login`, `status` — project setup and auth
@@ -43,10 +43,10 @@ dbo $ARGUMENTS
 | `init` | Initialize `.app/` configuration |
 | `login` / `logout` | Authenticate / clear session |
 | `status` | Show config, domain, session info |
-| `clone` | Clone an app to local project structure (media filtered by scope: app/user/foreign) |
-| `pull` | Pull records to local files |
+| `clone` | Full project setup: config, bin dirs, dependencies, schema, then all records. Also used to refresh deps/schema without a full re-clone (see below). |
+| `pull` | Content-only update — re-downloads changed records into existing local files. No dependency sync, no config changes, no scaffolding. Use this for routine day-to-day syncing. |
 | `push` | Push local changes to server |
-| `add` | Add a new file to DBO.io |
+| `adopt` | Create metadata companion for a local file (required before `push` for new files). Always pass `-e <entity>` — auto-inference is unreliable for content files. |
 | `diff` | Compare local files vs server versions |
 | `rm` | Remove file and stage server deletion |
 | `deploy` | Push a file to DBO by UID or named shorthand |
@@ -54,6 +54,19 @@ dbo $ARGUMENTS
 | `run` | Run a named script from `.app/scripts.json` |
 | `install` | Install/upgrade CLI, plugins (alias: `i`) |
 
+## clone vs pull — when to use each
+
+| Situation | Command |
+|-----------|---------|
+| First-time project setup | `dbo clone` |
+| Get latest file changes from server (routine) | `dbo pull` |
+| Refresh a dependency app (`app_dependencies/`) | `dbo clone --dependencies <name> -y` |
+| Refresh schema.json from server | `dbo clone --schema -y` (also re-clones records) |
+| Add a new dependency app to the project | `dbo clone --dependencies <name> -y` |
+| Re-clone without touching deps | `dbo clone --no-deps` |
+
+`dbo pull` is a subset of `dbo clone`. It calls the same underlying logic but skips config setup, dependency sync, directory scaffolding, and collision detection. Use `pull` whenever you just need updated file content.
+
 ## Common workflows
 
 ```bash
@@ -61,6 +74,12 @@ dbo $ARGUMENTS
 dbo init --domain my-domain.com --app myapp --clone
 dbo login
 
+# Routine content sync (day-to-day)
+dbo pull                          # re-download changed records
+dbo pull -y                       # auto-accept all incoming changes
+dbo pull -e content               # only content records
+dbo pull --dry-run                # preview what would change
+
 # Edit and push
 dbo push                          # push all changes in current dir
 dbo push lib/bins/app/assets/     # push specific directory
@@ -76,14 +95,22 @@ dbo push --no-scripts             # push without any hooks
 dbo deploy css:colors             # deploy using deploy_config.json shorthand
 dbo deploy albain3dwkofbhnd1qtd1q # deploy by UID directly
 
-# Pull
-dbo pull -e content --filter 'AppID=10100'
-
-# Add new files
-dbo add assets/css/newstyle.css
-dbo add .                         # scan for un-added files
+# Add a new file (adopt → push — both steps required for new assets)
+# Always pass -e <entity>. Auto-inference is unreliable; omitting -e causes failure.
+dbo adopt -e content lib/bins/app/assets/css/newstyle.css   # HTML/CSS/JS → content
+dbo push lib/bins/app/assets/css/newstyle.css
+dbo adopt -e media lib/bins/app/assets/img/logo.png         # images/binaries → media
+dbo push lib/bins/app/assets/img/logo.png
 
 # Compare and merge
 dbo diff                          # compare all local vs server
 dbo diff -y                       # auto-accept all server changes
+
+# Refresh dependencies and/or schema
+# clone is the dependency/schema refresh mechanism — not intuitive from the name.
+# --dependencies adds the app to config.json deps (union) then syncs only those apps (force).
+dbo clone --dependencies operator -y              # re-fetch one dependency
+dbo clone --dependencies _system,operator -y     # multiple deps (comma-separated)
+dbo clone --schema -y                            # refresh schema.json (also re-clones records)
+dbo clone --dependencies operator --schema -y   # dep + schema in one pass
 ```

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

@@ -140,7 +140,6 @@ my-project/
 │   │   └── 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)
@@ -149,7 +148,7 @@ my-project/
 │   ├── integration/    # Integration entity records
 │   ├── security/       # Security policy records
 │   ├── security_column/ # Column-level security records
-│   ├── data_source/    # (created when data sources exist)
+│   ├── data_source/    # Data source configs + entity (table) definitions
 │   ├── group/          # (created when groups exist)
 │   ├── site/           # (created when sites exist)
 │   └── redirect/       # (created when redirects exist)
@@ -203,7 +202,9 @@ Per-user settings (plugin scopes, completed migrations) are stored globally in `
 
 > **Upgrading to 0.16.0+**: `metadata_templates.json` is renamed to `metadata_schema.json`. The `_contentColumns` field in metadata files is renamed to `_companionReferenceColumns`. Extension companion file prompts during `dbo clone` are replaced by automatic derivation from `descriptor_definition` `form-control-code` data. Migration 011 runs automatically on first use.
 
-> **Upgrading to 0.14.0+**: Metadata files now use `name.metadata~uid.json` instead of `name~uid.metadata.json`. Migration 008 automatically renames all metadata files.
+> **Upgrading to 0.19.0+**: Metadata filenames no longer include `~UID` (e.g. `colors.metadata.json` instead of `colors.metadata~uid.json`). The UID is stored inside the JSON. Migration 013 automatically renames all metadata files.
+
+> **Upgrading to 0.14.0+**: Metadata files previously used `name.metadata~uid.json` instead of `name~uid.metadata.json`. Migration 008 handles this rename automatically.
 
 > **Upgrading to 0.13.3+**: Entity and extension companion files no longer include `~UID` in the filename. Migration 007 automatically renames legacy files.
 
@@ -298,8 +299,11 @@ Certain files live at the **project root** (not inside `lib/`) but are still tra
 | `manifest.json` | content | Yes | [PWA web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) |
 | `CLAUDE.md` | content | No | Claude Code project instructions |
 | `README.md` | content | Yes | Project readme |
+| `package.json` | content | No | Node.js package metadata and scripts |
+| `.dboignore` | content | No | DBO CLI ignore patterns |
+| `.gitignore` | content | No | Git ignore patterns |
 
-**`dbo clone`** writes all three to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description).
+**`dbo clone`** writes all six to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description, `package.json` as a minimal stub). Matching works regardless of the server record's `BinID`: records are matched by name, `@`-reference, or `Path`, then relocated to the root — whether they live in `lib/bins/app/`, another bin, or have `BinID=null`. Records with `BinID=null` that aren't in the configured list are also promoted to the project root automatically.
 
 **`dbo push`** auto-creates the companion metadata in `lib/bins/app/` for any listed root file that exists locally but has no tracked metadata yet — no manual `dbo adopt` needed before the first push.
 
@@ -322,11 +326,11 @@ The list of root content files is stored in `.app/config.json` under `rootConten
 
 ```json
 {
-  "rootContentFiles": ["CLAUDE.md", "README.md", "manifest.json"]
+  "rootContentFiles": ["CLAUDE.md", "README.md", "manifest.json", "package.json", ".dboignore", ".gitignore"]
 }
 ```
 
-- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json"]`
+- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json", "package.json", ".dboignore", ".gitignore"]`
 - **`[]`, `false`, or `null`**: feature disabled — no root content files are auto-managed
 - **Custom list**: any filename can be added; metadata is derived from the file extension
 
@@ -424,7 +428,7 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `--clone` | Clone the app after initialization |
 | `-g, --global` | Install Claude commands globally (`~/.claude/commands/`) |
 | `--local` | Install Claude commands to project (`.claude/commands/`) |
-| `--scaffold` | Pre-create standard project directories (`app_version`, `automation`, `bins`, `data_source`, `docs`, `extension`, `group`, `integration`, `site`, `src`, `tests`, `trash`) |
+| `--scaffold` | Pre-create standard project directories (`app_version`, `automation`, `bins`, `data_source`, `docs`, `extension`, `group`, `integration`, `site`, `src`, `tests`, `trash`). Note: `data_source/` is always scaffolded and also holds `entity` (table definition) records |
 | `--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` |
@@ -490,7 +494,7 @@ The project's reference domain is stored in `.app/<shortName>.metadata.json._dom
 7. **Saves `.app/directories.json`** — maps BinIDs to directory paths for file placement
 8. **Writes content files** — decodes base64 content, creates `*.metadata.json` + content files in the correct bin directory. Filename columns and companion file extraction preferences are auto-applied with sensible defaults on first clone (use `--configure` to re-prompt)
 9. **Downloads media files** — classifies records into three scopes before downloading: `app` (`/media/<app>/app/...` or no FullPath — always downloaded), `user` (`/media/<app>/user/...` — opt-in, preference saved as `UserMedia` in `config.json`), and `foreign` (`/media/<other_app>/...` — silently skipped with stale metadata written). Fetches using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`. 404 errors create stale metadata to prevent re-prompting. Errors are logged to `.app/errors.log`
-10. **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/`)
+10. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `entity`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory. Note: `entity` (table definitions) shares `lib/data_source/` with `data_source` records rather than using a separate directory
 11. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
 12. **Saves `.app/<shortName>.metadata.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
 13. **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
@@ -584,13 +588,14 @@ Where do you want me to place filename.ext?
 
 #### 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 types that correspond to project directories (`extension`, `app_version`, `data_source`, `entity`, `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/` |
+| `entity` | `data_source/` (co-located with data source records) |
 | `site` | `site/` |
 | `group` | `group/` |
 | `integration` | `integration/` |
@@ -600,7 +605,7 @@ For each entity type, the CLI prompts to choose which column becomes the filenam
 
 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 `_companionReferenceColumns` array (legacy name: `_contentColumns`, supported for backward compatibility).
 
-**Companion file naming convention:** Only `.metadata.json` files carry the `~UID` suffix (e.g. `Add-Asst-Execute-Security.metadata~wxl6ivcwfkix3zgantszjg.json`). Companion content files use the natural base name without `~UID` (e.g. `Add-Asst-Execute-Security.String5.html`). When a `{title}` is defined in the `@reference` expression (see [Metadata Schema](#metadata-schema)), the title replaces the column name in the filename (e.g. `Add-Asst-Execute-Security.Add-Form-Parameters.js` instead of `Add-Asst-Execute-Security.String5.js`). If two records share the same name within a directory, the second gets a `-1` suffix. Migration 007 automatically renames legacy `~UID` companion files to the natural convention.
+**Companion file naming convention:** Metadata files use `name.metadata.json` (e.g. `Add-Asst-Execute-Security.metadata.json`). The UID is stored inside the JSON, not in the filename. Companion content files use the natural base name (e.g. `Add-Asst-Execute-Security.String5.html`). When a `{title}` is defined in the `@reference` expression (see [Metadata Schema](#metadata-schema)), the title replaces the column name in the filename (e.g. `Add-Asst-Execute-Security.Add-Form-Parameters.js` instead of `Add-Asst-Execute-Security.String5.js`). If two records share the same name within a directory, the second gets a `-1` suffix (e.g. `Add-Asst-Execute-Security-1.metadata.json`); content records have priority over output records for the unsuffixed slot.
 
 Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
@@ -644,7 +649,7 @@ dbo clone -e extension --descriptor-types false       # Flat layout (no descript
 
 #### Entity children embedding
 
-When a server entity record contains nested child records (e.g., `entity_column` records nested under `entity` parents), `dbo clone` embeds them inline in the parent's `.metadata~uid.json` file under a `children` key:
+When a server entity record contains nested child records (e.g., `entity_column` records nested under `entity` parents), `dbo clone` embeds them inline in the parent's `.metadata.json` file under a `children` key:
 
 ```json
 {
@@ -693,7 +698,8 @@ project/
   docs/                      # ← root-placed documentation MD files (optional)
     MyDoc.md
   data_source/
-    MySQL-Primary.metadata.json
+    MySQL-Primary.metadata.json    # _entity: "data_source"
+    Users.metadata.json            # _entity: "entity" (table defs co-locate here)
   site/
     MainSite.metadata.json
   # Media files placed by BinID into bins/ (alongside content)

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

@@ -6,7 +6,7 @@ description: >-
   or when the white-paper provides architecture context but you need behavioral
   rules. Covers file operations, build recipes, metadata handling, and common
   gotchas.
-user-invokable: true
+user-invocable: true
 ---
 
 # DBO Project Cookbook
@@ -20,12 +20,13 @@ For architecture context, load the **white-paper** skill. For CLI command refere
 ## DOs
 
 - **DO use UIDs, not numeric IDs, in templates.** Numeric IDs change across environments (dev → staging → prod). UIDs are stable and portable.
-- **DO run `dbo adopt` before pushing new files.** Every file in `lib/` needs a metadata companion. `dbo adopt path/to/file -e {entity}` creates one. Without it, `dbo push` won't know what server record to target.
+- **DO always pass `-e <entity>` when running `dbo adopt`.** Every file in `lib/` needs a metadata companion. `dbo adopt path/to/file -e {entity}` creates one. Without it, `dbo push` won't know what server record to target. **Never omit `-e`** — auto-inference fails for most `lib/bins/` files because the directory maps to multiple entity types. Use `-e content` for HTML/CSS/JS/SQL, `-e media` for images and binaries.
 - **DO build from `src/` before pushing compiled assets.** Check `.app/scripts.json` for the build command. Run `npm run build` or the specific build script, then push the compiled output from `lib/`.
 - **DO check `.app/scripts.json` for build/postpush chains before manual deploys.** A file may have postpush hooks that auto-deploy dependent assets. Pushing manually with `dbo deploy` bypasses these chains.
-- **DO read the metadata file before modifying a server-tracked file.** The `.metadata~{uid}.json` companion tells you what entity, column, and record the file maps to. This context prevents wrong-target pushes.
+- **DO read the metadata file before modifying a server-tracked file.** The `.metadata.json` companion tells you what entity, column, and record the file maps to (check the `UID` field inside the JSON). This context prevents wrong-target pushes.
 - **DO use `dbo diff` to verify local vs server state before bulk pushes.** Catches unexpected server-side changes that would be overwritten.
 - **DO check `app_dependencies/` for parent app patterns when building extensions.** Descriptor definitions, CSS design tokens, and JS APIs from the parent app define what's available.
+- **DO know that `dbo clone` skips dependencies that are already up to date.** Before re-cloning a dependency, the CLI hits `/api/app/object/<name>?UpdatedAfter=<stored-date>` and compares `_LastUpdated`. If the server hasn't changed, the dep is skipped silently. Use `--force` or `--schema` to bypass this check and force a re-clone.
 - **DO use the REST API with `.app/cookies.txt` for data operations, CLI for file operations.** The CLI handles metadata sync; the API handles data reads/writes. Don't cross these boundaries.
 - **DO check `.app/deploy_config.json` for existing shorthands before creating deploy commands.** Shorthands are auto-generated by `dbo clone` and `dbo adopt`.
 - **DO use `dbo push --confirm false` to validate before committing a push.** Dry-run catches issues without touching the server.
@@ -135,6 +136,15 @@ Look at `targets.{file}.build` for compile commands and `targets.{file}.postpush
 **Cause:** You pushed only the content record but not the media companion (or vice versa).
 **Fix:** Push both — check `deploy_config.json` for paired `{name}` and `{name}_media` entries.
 
+### `dbo adopt` fails — entity cannot be inferred
+**Symptom:** `dbo adopt path/to/file` errors with "entity cannot be inferred" or similar.
+**Cause:** `-e <entity>` was omitted. Auto-inference only works for exact directive template matches. Files in `lib/bins/` (HTML, CSS, JS, SQL) almost never infer correctly because `lib/bins/` maps to multiple entity types.
+**Fix:** Always pass `-e content` for text/code files, `-e media` for images and binaries:
+```bash
+dbo adopt lib/bins/app/user_first_names.html -e content
+dbo adopt lib/bins/app/assets/img/logo.png -e media
+```
+
 ### Wrong entity type on adopt
 **Symptom:** Pushed file lands in unexpected server location.
 **Cause:** Used wrong `-e` flag on `dbo adopt` (e.g., `-e media` for a text file).

package/plugins/claude/dbo/skills/white-paper/SKILL.md

@@ -49,10 +49,9 @@ project-root/
 ├── lib/                     # Server-mapped files (mirrors DBO table data)
 │   ├── bins/                # Bin entities and their children (see Bin Mapping below)
 │   ├── extension/           # Extension records, sub-foldered by Descriptor
-│   ├── entity/              # Entity metadata files
+│   ├── data_source/         # Data source configs + entity (table) definitions
 │   ├── site/                # Site definitions
 │   ├── security/            # Security rule records
-│   ├── data_source/         # Data source configurations
 │   └── app_version/         # App version metadata
 │
 ├── docs/                    # Project documentation (scripts, embeds, pages, components)
@@ -83,11 +82,11 @@ Files belonging to a `bin` entity are placed in directories matching their BinID
 }
 ```
 
-So `lib/bins/app/assets/css/colors.css` lives inside the bin whose `fullPath` is `app/assets/css`. Every file has a companion `.metadata.json` (or `.metadata~{uid}.json`) containing the server record fields.
+So `lib/bins/app/assets/css/colors.css` lives inside the bin whose `fullPath` is `app/assets/css`. Every file has a companion `.metadata.json` (e.g. `colors.metadata.json`) containing the server record fields, including the `UID` field.
 
 ### Non-bin entities (no BinID column)
 
-Entities without a BinID column get their own directory under `lib/`, named after the entity: `lib/extension/`, `lib/entity/`, `lib/site/`, `lib/security/`, `lib/data_source/`, `lib/app_version/`.
+Entities without a BinID column get their own directory under `lib/`, named after the entity: `lib/extension/`, `lib/site/`, `lib/security/`, `lib/data_source/`, `lib/app_version/`. Exception: `entity` (table definitions) shares `lib/data_source/` rather than getting its own directory — both `_entity: "data_source"` and `_entity: "entity"` records live there.
 
 ### Extension special case
 
@@ -96,7 +95,7 @@ The `extension` entity has sub-folders based on the **Descriptor** column value:
 - `lib/extension/Widget/` — Widget extensions
 - `lib/extension/Descriptor Definition/` — Descriptor definitions themselves
 
-Each extension file follows: `{Name}.{ContentColumnName}.{ext}` with a companion `{Name}.metadata~{uid}.json`.
+Each extension file follows: `{Name}.{ContentColumnName}.{ext}` with a companion `{Name}.metadata.json` (UID stored inside the JSON).
 
 ## .app/ Configuration
 
@@ -152,10 +151,10 @@ When `app_dependencies/{app_name}/` exists (e.g., `app_dependencies/operator/`),
 ## CLI vs REST API
 
 ### Use the DBO CLI for:
-- **File operations**: `pull`, `push`, `add`, `clone`, `rm`, `diff`
+- **File operations**: `pull`, `push`, `adopt`, `clone`, `rm`, `diff` — for `adopt`, always pass `-e <entity>` (e.g., `-e content` for HTML/CSS/JS, `-e media` for images/binaries); entity cannot be inferred for standalone files in `lib/bins/`
 - **Deployment**: `deploy` (shorthand or UID), content deploy
 - **Project setup**: `init`, `login`, `status`
-- **Batch operations**: pushing directories, scanning for un-added files
+- **Batch operations**: pushing directories, scanning for unadopted files
 
 The CLI handles metadata management, change detection, and file-to-record synchronization automatically.
 
@@ -182,6 +181,48 @@ RowID:del{id};entity:entityName=true            # Delete
 ```
 Always include `_confirm=true`. Special values: `_{now}` (datetime), `_{null}` (null).
 
+## Creating New Assets
+
+Two approaches — choose based on whether the file exists locally first or on the server first.
+
+### File-first (CLI)
+
+Use when you're creating a new file locally and want the server to create the record.
+
+```bash
+# 1. Write the file in the correct lib/ subdirectory
+# 2. Create the metadata companion (required before push)
+dbo adopt -e content lib/bins/app/my-file.html   # HTML/CSS/JS/SQL → content
+dbo adopt -e media lib/bins/app/assets/img/x.png # images/binaries → media
+
+# 3. Push — inserts a new record on the server, assigns a UID, updates local metadata
+dbo push lib/bins/app/my-file.html
+```
+
+Always pass `-e <entity>` to `adopt`. Entity cannot be inferred for standalone files in `lib/bins/` because the directory maps to multiple entity types.
+
+### Server-first (REST API)
+
+Use when you want to create the server record first, then pull the file locally. Required fields for the insert come from three local config files:
+
+- **`.app/<app_short_name>.metadata_schema.json`** — entity schema: which columns are required, their types and allowed values
+- **`.app/directories.json`** — BinID for the target directory (needed for bin-based entities like `content` and `media`)
+- **`.app/config.json`** — `AppID`, `AppUID`, and other app-level fields required on most records
+
+```bash
+# 1. Insert the record via REST API (RowID:add1 — must use RowID:, not RowUID:)
+curl -b .app/cookies.txt \
+  "https://{{domain}}/api/input/submit?_confirm=true" \
+  --data-urlencode 'RowID:add1;column:content.BinID=11042' \
+  --data-urlencode 'RowID:add1;column:content.AppID={{appID}}' \
+  --data-urlencode 'RowID:add1;column:content.Name=My File'
+
+# 2. Pull to create the local file and metadata companion
+dbo pull -e content --filter 'Name=My File'
+```
+
+After pull, the file appears in `lib/bins/` at the path matching its BinID in `directories.json`, with a `.metadata.json` companion.
+
 ## docs/ Directory
 
 Contains Markdown documentation for this project's components — scripts, embeds, pages, UI features. These are project-specific references generated or maintained alongside development. Read these to understand documented behaviors of the current app.
@@ -213,7 +254,7 @@ The `test/` directory is for developer and Claude Code test scripts. Tests targe
 | Write/update data | REST API | `POST /api/input/submit` |
 | Pull files from server | CLI | `dbo pull -e content` |
 | Push local changes | CLI | `dbo push path/to/file` |
-| Add new file to server | CLI | `dbo add path/to/file` |
+| Add new file to server | CLI | `dbo adopt path/to/file -e <entity>` |
 | Deploy by shorthand | CLI | `dbo deploy css:colors` |
 | Deploy by UID | CLI | `dbo deploy {uid}` |
 | Compare with server | CLI | `dbo diff` |

package/plugins/claude/dbo/skills/white-paper/references/api-reference.md

@@ -87,7 +87,7 @@ RowID:{ref};column:{entity}.{Column}={value}
 | `{id}` or `{uid}` | Update existing record |
 | `del{id}` | Delete record |
 
-`RowID:` and `RowUID:` are interchangeable. Use `RowUID:` for cross-environment stability.
+`RowID:` and `RowUID:` are interchangeable for updates and deletes. Use `RowUID:` for cross-environment stability. **Inserts (`add1`, `add2`, …) must use `RowID:` — `RowUID:` does not work for inserts.**
 
 ### Cross-referencing within a batch
 ```

package/plugins/claude/track/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "track",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Changelog and Track API logging for Claude Code — automatically logs changes to changelog.md and the remote Track task_log on every session",
   "author": {
     "name": "DBO.io"

package/src/commands/adopt.js

@@ -159,7 +159,7 @@ async function adoptSingleFile(filePath, entityArg, options) {
   // These files live at the project root but their metadata goes in lib/bins/app/.
   // They bypass the dboignore check and entity inference.
   const rootFiles = await loadRootContentFiles();
-  if (rootFiles.includes(fileName) && relPath === fileName) {
+  if (rootFiles.some(f => f.toLowerCase() === fileName.toLowerCase()) && relPath === fileName) {
     const appConfig = await loadAppConfig();
     const structure = await loadStructureFile();
     const appBin = findBinByPath('app', structure);
@@ -189,7 +189,8 @@ async function adoptSingleFile(filePath, entityArg, options) {
       }
     }
 
-    const tmpl = ROOT_FILE_TEMPLATES[fileName] || { Extension: ext, Public: 0, Active: 1, Title: fileName };
+    const tmplKey = Object.keys(ROOT_FILE_TEMPLATES).find(k => k.toLowerCase() === fileName.toLowerCase());
+    const tmpl = (tmplKey ? ROOT_FILE_TEMPLATES[tmplKey] : null) || { Extension: ext, Public: 0, Active: 1, Title: fileName };
     const meta = {
       _entity: 'content',
       _companionReferenceColumns: ['Content'],
@@ -292,7 +293,7 @@ async function adoptSingleFile(filePath, entityArg, options) {
       Name: docBase,
     };
     if (appConfig.AppID) docMeta.AppID = appConfig.AppID;
-    const contentCol = 'String10';
+    const contentCol = 'Text';
     docMeta[contentCol] = `@/${relPath}`;
     docMeta._companionReferenceColumns = [contentCol];