@dboio/cli 0.19.4 → 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)
@@ -157,7 +156,9 @@ my-project/
 ├── test/               # Project-level tests
 ├── trash/              # Staged soft-deleted files from dbo rm
 ├── docs/               # Project documentation and docs entities
-├── manifest.json       # PWA web app manifest (auto-generated from app metadata)
+├── manifest.json       # PWA web app manifest (root content file — server-tracked)
+├── CLAUDE.md           # Claude Code instructions (root content file — server-tracked)
+├── README.md           # Project readme (root content file — server-tracked)
 ├── .gitignore          # Tells Git to ignore files in the repo sync
 ├── .dboignore          # Tells dbo cli to ignore files in commands
 ├── package.json        # Metadata, scripts, and dependency list
@@ -201,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.
 
@@ -244,6 +247,7 @@ Use `dbo status` to see how many pending migrations exist.
 | `TicketSuggestionOutput` | string | Output UID for ticket suggestions (auto-set during init, default `ojaie9t3o0kfvliahnuuda`) |
 | `cloneSource` | `"default"` \| file path \| URL | Where the last `dbo clone` fetched app JSON from. `"default"` = server fetch via `AppShortName`; any other value = the explicit local file path or URL used. Set automatically after each successful clone. |
 | `ContentPlacement` | `bin` \| `path` | Where to place content files during clone (default: `bin`) |
+| `UserMedia` | `true` \| `false` | Whether to download user media (`/media/<app>/user/...`) during clone. Set on first clone via prompt (or `false` in non-interactive mode). |
 | `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
 | `dependencies` | string[] | Array of app short-names to auto-clone as read-only local checkouts. Default: `["_system"]` |
 | `dependencyLastUpdated` | object | Map of dependency short-name to last-cloned `_LastUpdated` ISO string |
@@ -286,20 +290,49 @@ Clone of the original app JSON from the server with entity entries replaced by `
 
 The `_domain` field in the app metadata file stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
 
-#### `manifest.json`
+#### Root content files (`manifest.json`, `CLAUDE.md`, `README.md`)
+
+Certain files live at the **project root** (not inside `lib/`) but are still tracked and synced to the server as `content` entities. Their metadata companions live in `lib/bins/app/` with a root-relative `@/` reference (`Content: "@/manifest.json"`).
+
+| File | Server entity | Public | Description |
+|------|--------------|--------|-------------|
+| `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 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.
+
+**`dbo adopt <filename>`** called from the project root also works for any root content file: it bypasses the `.dboignore` check and entity inference, and writes the metadata directly to `lib/bins/app/`.
 
-A [PWA web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) auto-generated during scaffolding (`dbo init` or `dbo clone`). Values are derived from `app.json` when available:
+**`manifest.json`** generated fields (when produced as a stub):
 
 | Field | Source |
 |-------|--------|
-| `name` | `<AppName> \| <domain>` |
+| `name` | `AppName` |
 | `short_name` | `AppShortName` |
 | `description` | `App.Description` |
 | `start_url` / `scope` | `/app/<ShortName>/ui/` |
-| `background_color` | Extracted from the `widget` extension matching the app's `ShortName` (field `String4`), defaults to `#ffffff` |
+| `background_color` | Extracted from the `widget` extension matching `ShortName` (field `String4`), defaults to `#ffffff` |
 | `theme_color` | `#000000` |
 
-The file is only created if absent — it is never overwritten by subsequent clones, so local edits (icons, screenshots, display overrides) are preserved. A companion `manifest.metadata.json` is auto-created by `dbo push` if missing, allowing the manifest to be pushed to the server as a content record.
+#### `rootContentFiles` config
+
+The list of root content files is stored in `.app/config.json` under `rootContentFiles`:
+
+```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", "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
 
 ### `.dboignore`
 
@@ -395,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` |
@@ -460,8 +493,8 @@ The project's reference domain is stored in `.app/<shortName>.metadata.json._dom
 6. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
 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** — fetches binary files (images, CSS, fonts) from the server using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, and saves with metadata. 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/`)
+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`, `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
@@ -526,6 +559,24 @@ This helps keep your app clean by removing database records for media files that
 
 In non-interactive mode (`-y`), stale cleanup is skipped (conservative default).
 
+#### Media scope filtering
+
+During `dbo clone`, media records are classified by their `FullPath` relative to the app short name:
+
+| Scope | Path pattern | Behavior |
+|-------|-------------|----------|
+| `app` | `/media/<app>/app/...` or no `FullPath` | Always downloaded |
+| `user` | `/media/<app>/user/...` | Downloaded only if `UserMedia=true` in `.app/config.json` |
+| `foreign` | `/media/<other_app>/...` | Never downloaded — stale metadata written to prevent re-prompts |
+
+On the first clone with user media present, you'll be prompted once:
+
+```
+App has 14 user media file(s) (e.g. "avatar.jpg"). Download user media? (saves preference)
+```
+
+The answer is saved as `UserMedia` in `.app/config.json` and reused on subsequent clones. In non-interactive mode (`-y`), user media defaults to skipped (`UserMedia=false`).
+
 #### Path resolution
 
 When a content record has both `Path` and `BinID`, the CLI prompts:
@@ -537,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/` |
@@ -553,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).
 
@@ -597,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
 {
@@ -646,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.4",
+  "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"
@@ -15,6 +15,11 @@
       "path": "skills/white-paper/SKILL.md",
       "name": "white-paper",
       "description": "DBO project context and architecture guide — project structure, file-to-server mapping, dependencies, CLI vs API boundaries"
+    },
+    {
+      "path": "skills/cookbook/SKILL.md",
+      "name": "cookbook",
+      "description": "Operational DOs and DON'Ts for working correctly in any DBO project — file operations, build recipes, metadata handling, gotchas"
     }
   ]
 }

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 |
-| `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)
@@ -157,7 +156,9 @@ my-project/
 ├── test/               # Project-level tests
 ├── trash/              # Staged soft-deleted files from dbo rm
 ├── docs/               # Project documentation and docs entities
-├── manifest.json       # PWA web app manifest (auto-generated from app metadata)
+├── manifest.json       # PWA web app manifest (root content file — server-tracked)
+├── CLAUDE.md           # Claude Code instructions (root content file — server-tracked)
+├── README.md           # Project readme (root content file — server-tracked)
 ├── .gitignore          # Tells Git to ignore files in the repo sync
 ├── .dboignore          # Tells dbo cli to ignore files in commands
 ├── package.json        # Metadata, scripts, and dependency list
@@ -201,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.
 
@@ -244,6 +247,7 @@ Use `dbo status` to see how many pending migrations exist.
 | `TicketSuggestionOutput` | string | Output UID for ticket suggestions (auto-set during init, default `ojaie9t3o0kfvliahnuuda`) |
 | `cloneSource` | `"default"` \| file path \| URL | Where the last `dbo clone` fetched app JSON from. `"default"` = server fetch via `AppShortName`; any other value = the explicit local file path or URL used. Set automatically after each successful clone. |
 | `ContentPlacement` | `bin` \| `path` | Where to place content files during clone (default: `bin`) |
+| `UserMedia` | `true` \| `false` | Whether to download user media (`/media/<app>/user/...`) during clone. Set on first clone via prompt (or `false` in non-interactive mode). |
 | `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
 | `dependencies` | string[] | Array of app short-names to auto-clone as read-only local checkouts. Default: `["_system"]` |
 | `dependencyLastUpdated` | object | Map of dependency short-name to last-cloned `_LastUpdated` ISO string |
@@ -286,20 +290,49 @@ Clone of the original app JSON from the server with entity entries replaced by `
 
 The `_domain` field in the app metadata file stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
 
-#### `manifest.json`
+#### Root content files (`manifest.json`, `CLAUDE.md`, `README.md`)
+
+Certain files live at the **project root** (not inside `lib/`) but are still tracked and synced to the server as `content` entities. Their metadata companions live in `lib/bins/app/` with a root-relative `@/` reference (`Content: "@/manifest.json"`).
+
+| File | Server entity | Public | Description |
+|------|--------------|--------|-------------|
+| `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 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.
+
+**`dbo adopt <filename>`** called from the project root also works for any root content file: it bypasses the `.dboignore` check and entity inference, and writes the metadata directly to `lib/bins/app/`.
 
-A [PWA web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) auto-generated during scaffolding (`dbo init` or `dbo clone`). Values are derived from `app.json` when available:
+**`manifest.json`** generated fields (when produced as a stub):
 
 | Field | Source |
 |-------|--------|
-| `name` | `<AppName> \| <domain>` |
+| `name` | `AppName` |
 | `short_name` | `AppShortName` |
 | `description` | `App.Description` |
 | `start_url` / `scope` | `/app/<ShortName>/ui/` |
-| `background_color` | Extracted from the `widget` extension matching the app's `ShortName` (field `String4`), defaults to `#ffffff` |
+| `background_color` | Extracted from the `widget` extension matching `ShortName` (field `String4`), defaults to `#ffffff` |
 | `theme_color` | `#000000` |
 
-The file is only created if absent — it is never overwritten by subsequent clones, so local edits (icons, screenshots, display overrides) are preserved. A companion `manifest.metadata.json` is auto-created by `dbo push` if missing, allowing the manifest to be pushed to the server as a content record.
+#### `rootContentFiles` config
+
+The list of root content files is stored in `.app/config.json` under `rootContentFiles`:
+
+```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", "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
 
 ### `.dboignore`
 
@@ -395,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` |
@@ -460,8 +493,8 @@ The project's reference domain is stored in `.app/<shortName>.metadata.json._dom
 6. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
 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** — fetches binary files (images, CSS, fonts) from the server using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`, and saves with metadata. 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/`)
+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`, `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
@@ -526,6 +559,24 @@ This helps keep your app clean by removing database records for media files that
 
 In non-interactive mode (`-y`), stale cleanup is skipped (conservative default).
 
+#### Media scope filtering
+
+During `dbo clone`, media records are classified by their `FullPath` relative to the app short name:
+
+| Scope | Path pattern | Behavior |
+|-------|-------------|----------|
+| `app` | `/media/<app>/app/...` or no `FullPath` | Always downloaded |
+| `user` | `/media/<app>/user/...` | Downloaded only if `UserMedia=true` in `.app/config.json` |
+| `foreign` | `/media/<other_app>/...` | Never downloaded — stale metadata written to prevent re-prompts |
+
+On the first clone with user media present, you'll be prompted once:
+
+```
+App has 14 user media file(s) (e.g. "avatar.jpg"). Download user media? (saves preference)
+```
+
+The answer is saved as `UserMedia` in `.app/config.json` and reused on subsequent clones. In non-interactive mode (`-y`), user media defaults to skipped (`UserMedia=false`).
+
 #### Path resolution
 
 When a content record has both `Path` and `BinID`, the CLI prompts:
@@ -537,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/` |
@@ -553,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).
 
@@ -597,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
 {
@@ -646,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)