@dboio/cli 0.19.7 → 0.20.3

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.3",
   "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/docs/dual-platform-maintenance.md

@@ -0,0 +1,135 @@
+# Dual-Platform Maintenance Strategy
+
+## Overview
+
+The dbo.io API runs on two parallel codebases during the .NET Core migration period:
+
+- **`src/webapp-framework/`** — ASP.NET 4.7.2 (Windows), the current production platform
+- **`src/webapp-core/`** — .NET Core 8 (Linux), functionally tested, being prepared for production
+
+Both share identical `App_Code/` directories containing all business logic (~249 .cs files). Going forward, new feature work must be applied to both codebases until webapp-framework is retired.
+
+## File Structure
+
+### Shared Code (`App_Code/dboio/`)
+
+These directories exist in both `webapp-framework` and `webapp-core` and must stay in sync for feature changes:
+
+- `Data/` — entities, data sources, API add-ons, app operations, output/query system
+- `Data/App/` — AppManager, application-level operations
+- `Data/DataSource/` — MySQL, SQL Server, ODBC data source implementations
+- `Data/Output/` — output rendering, query building
+- `Web/Controllers/` — all MVC/API controllers
+- `Web/Security/` — authentication, authorization, SAML
+- `Web/` — caching (ICacheProvider, Redis, HttpRuntime), session, delivery pipeline
+- `Util/` — encryption, email, file/zip utilities
+
+### webapp-framework Only (Windows)
+
+- `App_Start/` — legacy ASP.NET startup
+- `Web.config` + `web.*.config` — IIS configuration files
+- `Global.asax` / `Global.asax.cs` — application lifecycle
+- `Account/` — legacy account pages
+
+### webapp-core Only (Linux)
+
+- `Program.cs` — .NET Core entry point and middleware pipeline
+- `Middleware/` — 9 middleware classes (ported from HttpModules)
+- `Shims/` — compatibility shims (HttpContext, Cache, ConfigurationManager, CaseInsensitiveFileProvider)
+- `appsettings.json` / `appsettings.*.json` — .NET Core configuration
+- `log4net.config` — Core-specific logging configuration
+
+## Change Categories
+
+### Category 1: Core-Only Infrastructure
+
+Changes that only apply to `webapp-core`. No transfer to `webapp-framework` needed.
+
+Examples:
+- Middleware files (`Middleware/*.cs`)
+- Shim files (`Shims/*.cs`)
+- `Program.cs`
+- `appsettings*.json`, `log4net.config`
+- `App_Code/Properties/AssemblyInfo.cs` (platform-diverged)
+- `App_Code/Global.asax.cs` (platform-diverged)
+- Build/deploy scripts (`build/deploy-core.sh`, `build/boot-deploy.sh`)
+- AWS infrastructure (EFS, CloudWatch, Launch Templates)
+
+When a transfer review issue is created for Category 1 files, close it as "not planned."
+
+### Category 2: Shared Business Logic
+
+Changes to business logic in `App_Code/dboio/` that affect both platforms.
+
+Examples:
+- Entity classes, data access (`Data/`, `Data/App/`, `Data/DataSource/`)
+- Controllers (`Web/Controllers/`)
+- Security (`Web/Security/`)
+- Cache logic (`Web/` cache providers)
+- Utility classes (`Util/`)
+- Any bug fix or feature in shared code
+
+When a transfer review issue is created for Category 2 files, apply the equivalent change to `src/webapp-framework/App_Code/`, then close the issue.
+
+## Automated Transfer Review Workflow
+
+A GitHub Action (`.github/workflows/transfer-review.yml`) monitors pushes to all branches.
+
+### How it works
+
+1. Triggers on any push that modifies files under `src/webapp-core/App_Code/`
+2. Filters out excluded subdirectories (configurable in the workflow YAML)
+3. Creates a GitHub issue labeled `netcore-aspnet-transfer`
+4. Lists all changed App_Code files, the commit hash, branch, and author
+
+### Reviewing transfer issues
+
+1. Open the issue and review the changed files
+2. If all changes are Category 1 (Core-only): close as "not planned"
+3. If any changes are Category 2 (shared): apply to `webapp-framework`, then close with a reference to the transfer commit
+
+### Exclusion list
+
+The workflow YAML contains an `EXCLUDE_PATTERNS` array. Add subdirectory names to suppress issues for known Core-only paths within `App_Code/`:
+
+```bash
+EXCLUDE_PATTERNS=(
+  # "Properties"
+  # Add more as patterns emerge
+)
+```
+
+## Commit Message Conventions
+
+No strict format required, but these prefixes help identify change scope:
+
+- **`webapp-core:`** — Core-only changes (Category 1, no transfer needed)
+- **`webapp-framework:`** — Framework-only changes
+- **No prefix** — changes that apply to both platforms, or general feature work
+
+Examples:
+- `webapp-core: fix middleware ordering for auth` (Category 1)
+- `Task XXXX | entity: add new validation rule #NNN` (Category 2, needs transfer)
+
+## Development Flow
+
+1. New business logic typically starts in `webapp-framework` (production platform)
+2. After committing, manually apply the same change to `webapp-core`
+3. Core-only infrastructure work happens only in `webapp-core`
+4. The transfer review workflow catches the reverse case (Core-first changes that may need Framework transfer)
+
+## Retirement Criteria for webapp-framework
+
+`webapp-framework` can be retired when ALL of the following are met:
+
+1. **Functional parity** — webapp-core handles all production traffic without regressions
+2. **Production cutover** — load balancer routes 100% of traffic to Core servers
+3. **Stability period** — at least 30 days of production traffic on Core with no regressions
+4. **Client sign-off** — explicit approval to decommission Windows servers
+5. **Rollback plan verified** — confirmed ability to revert to webapp-framework if needed
+
+After retirement:
+- Archive `src/webapp-framework/` (do not delete immediately)
+- Remove the transfer review workflow
+- Remove the `netcore-aspnet-transfer` label
+- Update this document

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).