@dboio/cli 0.16.2 → 0.19.0

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

@@ -62,7 +62,7 @@ Once installed, use `/dbo` in Claude Code:
 /dbo push assets/css/
 ```
 
-The plugin source lives in `plugins/claude/dbo/` at the repository root. Installed copies in `.claude/plugins/` are gitignored and managed by `dbo install`. Each plugin's installation scope (project or global) is stored per-plugin in `.dbo/config.local.json`.
+The plugin source lives in `plugins/claude/dbo/` at the repository root. Installed copies in `.claude/plugins/` are gitignored and managed by `dbo install`. Each plugin's installation scope (project or global) is stored in `~/.dbo/settings.json`.
 
 ---
 
@@ -122,8 +122,19 @@ When you run `dbo init --scaffold` or `dbo clone`, the following standard direct
 
 ```
 my-project/
-├── .dbo/               # Config, synchronization and session info for dbo cli commands
+├── .app/               # Config, synchronization and session info for dbo cli commands
+│   ├── config.json     # Domain, app metadata, placement preferences (committed)
+│   ├── <shortName>.json          # Server-state baseline for delta detection (committed)
+│   ├── <shortName>.metadata.json # Clone of original app JSON with @references (committed)
+│   ├── <shortName>.metadata_schema.json # Column templates per entity/descriptor (committed)
+│   ├── directories.json          # Bin directory mapping (committed)
+│   ├── synchronize.json          # Pending add/edit/delete staging (committed)
+│   ├── credentials.json          # Username, user ID (gitignored)
+│   ├── cookies.txt               # Session cookie (gitignored)
+│   └── scripts.json              # Build/push lifecycle hooks (committed)
 ├── .claude/            # Claude Code plugin config (commands, specs, plans, skills)
+├── app_dependencies/   # Read-only checkouts of dependency apps (gitignored)
+│   └── _system/        # System schema dependency
 ├── lib/                # All DBO server-managed assets
 │   ├── bins/           # Assets (contents, outputs, images, HTML, CSS)
 │   │   └── app/        # Default application bin
@@ -146,8 +157,6 @@ my-project/
 ├── test/               # Project-level tests
 ├── trash/              # Staged soft-deleted files from dbo rm
 ├── docs/               # Project documentation and docs entities
-├── app.json            # Clone of original app JSON with @references
-├── schema.json         # Instance-level entity/column schema fetched from the server during `dbo init`. Refreshed explicitly with `dbo clone --schema`.
 ├── manifest.json       # PWA web app manifest (auto-generated from app metadata)
 ├── .gitignore          # Tells Git to ignore files in the repo sync
 ├── .dboignore          # Tells dbo cli to ignore files in commands
@@ -161,51 +170,44 @@ my-project/
 
 ## Configuration
 
-All configuration is **directory-scoped**. Each project folder maintains its own `.dbo/` directory with its own domain and session. Switch environments by switching directories:
+All configuration is **directory-scoped**. Each project folder maintains its own `.app/` directory with its own domain and session. Switch environments by switching directories:
 
 ```bash
-~/projects/my-project/    → .dbo/ → my-domain.com
-~/projects/my-project-prod/    → .dbo/ → prod.dbo.io
+~/projects/my-project/    → .app/ → my-domain.com
+~/projects/my-project-prod/    → .app/ → prod.dbo.io
 ```
 
-### `.dbo/` directory contents
+### `.app/` directory contents
 
 | File | Purpose | Git |
 |------|---------|-----|
 | `config.json` | Domain, app metadata, placement preferences | Committable (shared) |
-| `config.local.json` | Per-user settings: plugin scopes, `_completedMigrations` (system-managed) | Gitignored (per-user) |
-| `ticketing.local.json` | Stored ticket IDs for submission error recovery | Gitignored (per-user) |
 | `credentials.json` | Username, user ID, UID, name, email (no password) | Gitignored (per-user) |
 | `cookies.txt` | Session cookie (Netscape format) | Gitignored (per-user) |
-| `structure.json` | Bin directory mapping (created by `dbo clone`) | Committable (shared) |
-| `metadata_schema.json` | Column templates per entity/descriptor (auto-generated by `dbo clone`; renamed from `metadata_templates.json`) | Committable (shared) |
+| `directories.json` | Bin directory mapping (created by `dbo clone`) | Committable (shared) |
+| `<shortName>.metadata_schema.json` | Column templates per entity/descriptor (auto-generated by `dbo clone`) | Committable (shared) |
 | `synchronize.json` | Pending deletions and sync state (updated by `dbo rm` and `dbo push`) | Committable (shared) |
-| `.app_baseline.json` | Server-state snapshot for delta detection — stores column values at last clone/push so `dbo push` can detect which columns changed locally. Read-only (chmod 444); auto-migrated from legacy root `.app.json`. | Committable (shared) |
+| `<shortName>.json` | Server-state snapshot for delta detection — stores column values at last clone/push so `dbo push` can detect which columns changed locally. Read-only (chmod 444). | Committable (shared) |
+| `<shortName>.metadata.json` | Clone of original app JSON with entity entries replaced by `@path/to/*.metadata.json` references | Committable (shared) |
 | `scripts.json` | Build/push lifecycle hooks (see [Script Hooks](#script-hooks)) | Committable (shared) |
 | `scripts.local.json` | Per-user hook overrides | Gitignored (per-user) |
+| `ticketing.local.json` | Stored ticket IDs for submission error recovery | Gitignored (per-user) |
 
-`dbo init` automatically adds `.dbo/credentials.json`, `.dbo/cookies.txt`, `.dbo/config.local.json`, `.dbo/ticketing.local.json`, and `.dbo/scripts.local.json` to `.gitignore` (creates the file if it doesn't exist).
+Per-user settings (plugin scopes, completed migrations) are stored globally in `~/.dbo/settings.json`.
 
-> **Upgrading from pre-0.9.9**: The baseline file `.app.json` in the project root has moved to `.dbo/.app_baseline.json`. Running any `dbo` command will auto-migrate the file. You can also manually remove the `.app.json` entry from your `.gitignore`.
+`dbo init` automatically adds `.app/credentials.json`, `.app/cookies.txt`, `.app/ticketing.local.json`, `.app/scripts.local.json`, `.app/errors.log`, and `app_dependencies/` to `.gitignore` (creates the file if it doesn't exist).
 
-> **Upgrading from pre-0.11.0**: `TransactionKeyPreset` now applies only to records that carry a `UID` column (core assets). Data records without a UID are always submitted with `RowID` regardless of the preset. Migration 001 runs automatically on first command after upgrade and logs a one-time notice.
+> **Upgrading to 0.18.0+**: The project directory has been restructured: `.dbo/` is renamed to `.app/`, `app.json` moves to `.app/<shortName>.metadata.json`, `schema.json` is removed (schema now sourced from `app_dependencies/_system/`), `.dbo/dependencies/` moves to `app_dependencies/`, `.app_baseline.json` becomes `<shortName>.json`, `structure.json` becomes `directories.json`, `metadata_schema.json` becomes `<shortName>.metadata_schema.json`, and `config.local.json` moves to `~/.dbo/settings.json`. Migration 012 runs automatically on first command after upgrade.
 
-> **Upgrading to 0.13.3+**: Entity and extension companion files no longer include `~UID` in the filename. Migration 007 automatically renames legacy `name~uid.Column.ext` files to `name.Column.ext` and updates `@references` in metadata.
+> **Upgrading to 0.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`. The UID has moved from the base name into the `.metadata~uid` suffix. Migration 008 automatically renames all metadata files. Output child companions use index-based naming (`Sales.column.CustomSQL.sql`, `Sales.column-1.CustomSQL.sql`) instead of UID-based naming.
->
-> | Record type | Example metadata file |
-> |---|---|
-> | Content | `colors.metadata~abc123.json` |
-> | Media | `logo.png.metadata~def456.json` |
-> | Output | `Sales.metadata~ghi789.json` |
-> | Extension | `MyExtension.metadata~jkl012.json` |
+> **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.16.0+**: `.dbo/metadata_templates.json` is renamed to `.dbo/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.13.3+**: Entity and extension companion files no longer include `~UID` in the filename. Migration 007 automatically renames legacy files.
 
 #### Automatic migrations
 
-When the CLI version is upgraded, one-time migration scripts in `tools/cli/src/migrations/` run automatically on the first command invocation in a project directory. Completed migration IDs are recorded in `.dbo/config.local.json` under `_completedMigrations` (per-user, gitignored) so each developer runs them independently and they never re-fire.
+When the CLI version is upgraded, one-time migration scripts in `tools/cli/src/migrations/` run automatically on the first command invocation in a project directory. Completed migration IDs are recorded in `~/.dbo/settings.json` under `_completedMigrations` (per-user, global) so each developer runs them independently and they never re-fire.
 
 To skip migrations for a single command run:
 
@@ -233,7 +235,7 @@ Use `dbo status` to see how many pending migrations exist.
 | Key | Values | Description |
 |-----|--------|-------------|
 | `domain` | hostname | DBO.io instance to connect to |
-| `AppID` | number | App ID (set by `dbo clone`, used by `dbo add`/`dbo input`) |
+| `AppID` | number | App ID (set by `dbo clone`, used by `dbo adopt`/`dbo input`) |
 | `AppUID` | string | App UID |
 | `AppName` | string | App display name |
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
@@ -250,20 +252,20 @@ Use `dbo status` to see how many pending migrations exist.
 
 ### App Dependencies
 
-The CLI automatically maintains local read-only checkouts of related apps under `.dbo/dependencies/<shortname>/`. By default, the `_system` app (which contains all entity, column, and extension descriptors for the connected instance) is always included.
+The CLI automatically maintains local read-only checkouts of related apps under `app_dependencies/<shortname>/`. By default, the `_system` app (which contains all entity, column, and extension descriptors for the connected instance) is always included.
 
 #### How it works
 
-- After `dbo init` or `dbo clone`, dependency apps are cloned into `.dbo/dependencies/`.
-- If an `app.json` contains a `Dependencies` column, those app short-names are merged into `.dbo/config.json` and also cloned.
+- After `dbo init` or `dbo clone`, dependency apps are cloned into `app_dependencies/`.
+- If an app JSON contains a `Dependencies` column, those app short-names are merged into `.app/config.json` and also cloned.
 - You can add dependencies explicitly with `dbo clone --dependencies operator,launchpad`.
 - Dependencies are only re-cloned when the server's `_LastUpdated` is newer than the locally stored timestamp — so subsequent runs are fast.
 - Dependency clone output is suppressed — a single summary line shows synced/failed/up-to-date status.
-- `.dbo/dependencies/` is excluded from `.gitignore` and `.dboignore` automatically.
+- `app_dependencies/` is excluded from `.gitignore` and `.dboignore` automatically.
 
 #### Schema merging from dependencies
 
-After dependency cloning, extension descriptor definitions from dependency schemas (`.dbo/dependencies/<name>/.dbo/metadata_schema.json`) are merged into the local `.dbo/metadata_schema.json`. This is useful when an app has no `descriptor_definition` extensions of its own but depends on an app (like `operator`) that does — the operator's descriptor definitions (widget, include, control, etc.) become available for local extension processing.
+After dependency cloning, extension descriptor definitions from dependency schemas (`app_dependencies/<name>/.app/<name>.metadata_schema.json`) are merged into the local `.app/<shortName>.metadata_schema.json`. This is useful when an app has no `descriptor_definition` extensions of its own but depends on an app (like `operator`) that does — the operator's descriptor definitions (widget, include, control, etc.) become available for local extension processing.
 
 #### Flags
 
@@ -276,13 +278,13 @@ After dependency cloning, extension descriptor definitions from dependency schem
 
 ### Root-level project files
 
-#### `app.json`
+#### `.app/<shortName>.metadata.json`
 
-Clone of the original app JSON from the server with entity entries replaced by `@path/to/*.metadata.json` references. Created by `dbo init` (empty `{}`) and populated by `dbo clone`. Committed to git.
+Clone of the original app JSON from the server with entity entries replaced by `@path/to/*.metadata.json` references. Created by `dbo clone`. Committed to git. (Formerly `app.json` in the project root.)
 
-#### `app.json._domain`
+#### `.app/<shortName>.metadata.json._domain`
 
-The `_domain` field in `app.json` stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
+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`
 
@@ -305,7 +307,7 @@ A gitignore-style file in the project root that controls which files and directo
 
 **Used by:**
 - `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
-- `dbo add .` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo add file.html`)
+- `dbo adopt ./` — directory scanning (which files/dirs to skip); also checked in single-file mode (`dbo adopt file.html`)
 - `dbo push` — metadata file discovery: skips matching `.metadata.json` / `_output~*.json` files AND any record whose companion content file (`@reference`) matches an ignore pattern
 
 **Bypass:** Use `dbo input -d '...'` to submit expressions for a file that would otherwise be ignored — `dbo input` never does file discovery so `.dboignore` does not apply.
@@ -331,9 +333,9 @@ bins/
 **Default patterns:**
 
 ```gitignore
-.dbo/              # DBO internal
+.app/              # DBO internal
+app_dependencies/  # Dependency checkouts
 *.dboio.json       # Export files
-app.json           # Clone output
 .git/              # Version control
 .gitignore
 node_modules/      # Node
@@ -406,7 +408,7 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 Clone an app from DBO.io to a local project structure. Creates directories, files, metadata, and populates `config.json` and `package.json`.
 
 ```bash
-# Clone using config (AppShortName from .dbo/config.json)
+# Clone using config (AppShortName from .app/config.json)
 dbo clone
 
 # Clone from a local JSON export file
@@ -433,7 +435,7 @@ dbo clone -e extension --descriptor-types false   # Clone extensions flat (no de
 | `--documentation-only` | When used with `-e extension`, clone only documentation extensions |
 | `--descriptor-types <bool>` | Sort extensions into descriptor sub-directories (default: `true`). Set to `false` to use flat `extension/` layout |
 | `--domain <host>` | Override domain. Triggers a domain-change confirmation prompt when it differs from the project reference domain |
-| `--schema` | Re-fetch `schema.json` from server before cloning |
+| `--schema` | Re-fetch schema from server before cloning |
 | `--force` | Skip source mismatch confirmation and change detection; re-processes all files |
 | `-y, --yes` | Auto-accept all prompts (also skips source mismatch confirmation) |
 | `-v, --verbose` | Show HTTP request details |
@@ -444,29 +446,29 @@ dbo clone -e extension --descriptor-types false   # Clone extensions flat (no de
 
 #### Domain change detection
 
-When cloning with a different domain than the project's reference domain (`app.json._domain` or `config.json.domain`), the CLI warns before proceeding. When `TransactionKeyPreset=RowID`, this escalates to a critical error because numeric IDs are not unique across domains — pushing to the wrong domain can corrupt records. In non-interactive mode (`-y`), RowUID domain changes proceed with a warning, but RowID domain changes throw a hard error.
+When cloning with a different domain than the project's reference domain (`.app/<shortName>.metadata.json._domain` or `config.json.domain`), the CLI warns before proceeding. When `TransactionKeyPreset=RowID`, this escalates to a critical error because numeric IDs are not unique across domains — pushing to the wrong domain can corrupt records. In non-interactive mode (`-y`), RowUID domain changes proceed with a warning, but RowID domain changes throw a hard error.
 
-The project's reference domain is stored in `app.json._domain` (committed to git) during clone, giving the CLI a stable cross-user baseline.
+The project's reference domain is stored in `.app/<shortName>.metadata.json._domain` (committed to git) during clone, giving the CLI a stable cross-user baseline.
 
 #### What clone does
 
-1. **Fetches schema** — downloads `schema.json` from the server if missing or explicitly requested (`--schema`). Regenerates `.dbo/metadata_schema.json` from the schema
-2. **Syncs dependencies** — clones dependency apps into `.dbo/dependencies/<shortname>/` (unless `--no-deps`). Merges extension descriptor definitions from dependency schemas into the local `.dbo/metadata_schema.json` (e.g., operator provides descriptor definitions for apps that lack their own)
+1. **Fetches schema** — downloads schema from the server if missing or explicitly requested (`--schema`). Regenerates `.app/<shortName>.metadata_schema.json` from the schema
+2. **Syncs dependencies** — clones dependency apps into `app_dependencies/<shortname>/` (unless `--no-deps`). Merges extension descriptor definitions from dependency schemas into the local `.app/<shortName>.metadata_schema.json` (e.g., operator provides descriptor definitions for apps that lack their own)
 3. **Loads app JSON** — from a local file, server API, or interactive prompt. A spinner shows progress while fetching from the server (responses can be slow as the JSON is assembled on demand)
-4. **Updates `.dbo/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`, `AppModifyKey` (if the app is locked), and `cloneSource` (the source used for this clone)
+4. **Updates `.app/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`, `AppModifyKey` (if the app is locked), and `cloneSource` (the source used for this clone)
 5. **Updates `package.json`** — populates `name`, `productName`, `description`, `homepage`, and `deploy` script
 6. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
-7. **Saves `.dbo/structure.json`** — maps BinIDs to directory paths for file placement
+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 `.dbo/errors.log`
+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/`)
 11. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
-12. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
+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
 
 #### Clone source tracking
 
-After every successful clone, the source is persisted as `cloneSource` in `.dbo/config.json`:
+After every successful clone, the source is persisted as `cloneSource` in `.app/config.json`:
 
 - `"default"` — app JSON was fetched from the server using `AppShortName` (the normal flow)
 - A file path or URL — set when an explicit `<source>` argument was provided (e.g. `dbo clone /path/to/export.json`)
@@ -505,7 +507,7 @@ When multiple records would create files at the same path (e.g., a `content` rec
   [media] colors.css (UID: def456)
 ```
 
-The rejected record is automatically staged for deletion in `.dbo/synchronize.json`. Run `dbo push` to delete it from the server.
+The rejected record is automatically staged for deletion in `.app/synchronize.json`. Run `dbo push` to delete it from the server.
 
 In non-interactive mode (`-y`), the first record is kept and others are auto-staged for deletion.
 
@@ -565,7 +567,7 @@ During clone, the CLI:
 2. **Creates sub-directories** under `extension/` for each mapped descriptor (e.g., `extension/Documentation/`, `extension/Includes/`)
 3. **Places unmapped extensions** directly in `extension/` — extensions with an unmapped or null `Descriptor` are placed in the root `extension/` directory (the legacy `_unsupported/` sub-directory is migrated automatically by Migration 011)
 4. **Prompts per descriptor** — filename column and content extraction prompts fire once per unique `Descriptor` value (not once for all extensions)
-5. **Persists the mapping** in `.dbo/structure.json` under `descriptorMapping`
+5. **Persists the mapping** in `.app/directories.json` under `descriptorMapping`
 
 **Config keys** (saved per descriptor in `config.json`):
 
@@ -591,18 +593,42 @@ dbo clone -e extension                               # Clone all extensions (all
 dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
 ```
 
-**`dbo add` auto-inference**: Running `dbo add docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `extension/documentation/` with the correct `@/` reference.
+**`dbo adopt` auto-inference**: Running `dbo adopt docs/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `lib/extension/documentation/` with the correct `@/` reference.
+
+#### 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:
+
+```json
+{
+  "_entity": "entity",
+  "UID": "abc123",
+  "Name": "contact",
+  "children": {
+    "entity_column": [
+      { "UID": "col1", "Name": "FirstName", "PhysicalOrderNumber": 1, "_LastUpdated": "2026-01-01T00:00:00" },
+      { "UID": "col2", "Name": "LastName", "PhysicalOrderNumber": 2, "_LastUpdated": "2026-01-02T00:00:00" }
+    ]
+  }
+}
+```
+
+Children are stored with all fields intact (including `_LastUpdated`, `_CreatedOn`, `UID`). Base64-encoded field values within child records are decoded to plain strings. This applies generically to all entity types that contain a `children` property in the server response.
+
+**Push behaviour**: `dbo push` detects changes within the `children` arrays by comparing against the baseline. Modified child records are submitted independently as input expressions (children before parent). Removing a child from the metadata file stages a delete in `synchronize.json`. The `children` key itself is never included in the parent's input expression.
+
+**Output hierarchy children**: Output child records (`output_value`, `output_value_filter`, `output_value_entity_column_rel`) are also embedded inline under `children`. Only the root output's `CustomSQL` is extracted as a companion `.sql` file — child `CustomSQL` values are stored inline as decoded strings.
 
 #### Output structure
 
 ```
 project/
-  .dbo/
+  .app/
     config.json              # Updated with app metadata
-    structure.json           # Bin directory mapping
+    directories.json         # Bin directory mapping
+    <shortName>.metadata.json # Clone of original with @references
   .gitignore                 # credentials.json + cookies.txt added
   package.json               # Updated with app info + deploy script
-  app.json                   # Clone of original with @references
   bins/                      # ← root for all bin-placed files
     app/                     # ← directory from children.bin
       thomas-scratch.md
@@ -687,7 +713,7 @@ During `dbo clone`, the CLI downloads media using a **fallback chain**:
 2. **`/dir/` route** — strips the `/media/` prefix from FullPath and uses the `/dir/` route
 3. **`/api/media/{uid}`** — UID-based endpoint as last resort (when no FullPath exists)
 
-If all attempts fail, the error is logged to `.dbo/errors.log` (JSONL format) with the record's UID, filename, FullPath, and error details.
+If all attempts fail, the error is logged to `.app/errors.log` (JSONL format) with the record's UID, filename, FullPath, and error details.
 
 #### Output hierarchy format
 
@@ -726,7 +752,7 @@ Key points:
 
 #### Metadata Schema
 
-During `dbo clone`, the CLI auto-generates `.dbo/metadata_schema.json` (formerly `metadata_templates.json`) — a file that records which columns each entity/descriptor uses. This file is seeded from the first cloned record of each type and can be manually edited afterwards.
+During `dbo clone`, the CLI auto-generates `.app/<shortName>.metadata_schema.json` — a file that records which columns each entity/descriptor uses. This file is seeded from the first cloned record of each type and can be manually edited afterwards.
 
 **File format:**
 
@@ -749,11 +775,11 @@ During `dbo clone`, the CLI auto-generates `.dbo/metadata_schema.json` (formerly
 | `String10=@reference` | Content reference — links to the file being added |
 | `String5=@reference:@Name[js]` | Content reference with filename source and extension |
 
-`dbo add` uses these templates to auto-detect the entity type from a file's directory placement and generate metadata without prompting. For example, `dbo add extension/include/nav.html` resolves to entity `extension` / descriptor `include` and applies the matching template.
+`dbo adopt` uses these templates to auto-detect the entity type from a file's directory placement and generate metadata without prompting. For example, `dbo adopt lib/extension/include/nav.html` resolves to entity `extension` / descriptor `include` and applies the matching template.
 
 #### `@reference` expression syntax
 
-The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo add`. The full grammar:
+The `=@reference` expression controls how companion files are named during `dbo clone` and `dbo adopt`. The full grammar:
 
 ```
 Column=@reference[:filenameSource][extPart][{title}]
@@ -793,7 +819,7 @@ Given a record with `Name="My-Widget"`, `Extension="html"`, `Ext=""` (empty):
 
 Authenticate with a DBO.io instance and store the session cookie.
 
-After successful authentication, the CLI automatically fetches and stores the current user's ID, UID, name, and email in `.dbo/credentials.json`. The ID and UID are used for automatic retry when server submissions require user identity (see [Automatic error recovery](#automatic-error-recovery)). The name and email are used to populate `package.json` author fields during `dbo clone`.
+After successful authentication, the CLI automatically fetches and stores the current user's ID, UID, name, and email in `.app/credentials.json`. The ID and UID are used for automatic retry when server submissions require user identity (see [Automatic error recovery](#automatic-error-recovery)). The name and email are used to populate `package.json` author fields during `dbo clone`.
 
 > **Note:** User info is currently retrieved via a separate API call after login. This is a temporary workaround — the authentication endpoint should include user info in its response directly.
 
@@ -836,13 +862,13 @@ dbo status
 
 Output:
 ```
-  Initialized: Yes (.dbo/)
+  Initialized: Yes (.app/)
   Domain: my-domain.com
   Username: user@example.com
   User ID: 10296
   Directory: /Users/me/projects/operator
   Session: Active (expires: 2026-03-15T10:30:00.000Z)
-  Cookies: /Users/me/projects/operator/.dbo/cookies.txt
+  Cookies: /Users/me/projects/operator/.app/cookies.txt
 
   Claude Code Plugins:
   dbo: ✓ global (~/.claude/commands/dbo.md)
@@ -850,7 +876,7 @@ Output:
 
 User ID is populated by `dbo login`. If it shows "(not set)", run `dbo login` to fetch it.
 
-Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `.dbo/config.local.json`.
+Plugin scopes (project or global) are displayed when plugins have been installed. Scopes are stored in `~/.dbo/settings.json`.
 
 ---
 
@@ -1407,7 +1433,7 @@ Apply macOS Finder color tags or Linux gio emblems to companion files based on t
 |-----|-------|---------|
 | `dbo:Synced` | 🟢 Green | File matches server — no local changes |
 | `dbo:Modified` | 🔵 Blue | Local edits not yet pushed |
-| `dbo:Untracked` | 🟡 Yellow | No metadata — not yet added with `dbo add` |
+| `dbo:Untracked` | 🟡 Yellow | No metadata — not yet adopted with `dbo adopt` |
 | `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
 
 ```bash
@@ -1458,7 +1484,7 @@ dbo rm --keep-local bins/app/ui/
 ```
 
 When removing a directory, the CLI:
-1. Looks up the BinID from `.dbo/structure.json`
+1. Looks up the BinID from `.app/directories.json`
 2. Recursively collects all sub-directories (processed leaves-first)
 3. Prompts: "Remove all files and directories", "Prompt for each file", or "Cancel"
 4. Stages each file's deletion, then each bin's deletion (`entity:bin`)
@@ -1476,8 +1502,8 @@ When removing a directory, the CLI:
 1. **Resolves metadata** — if given a content file, finds the companion `.metadata.json`
 2. **Reads row ID** — uses `_id` (shorthand) or derives from entity (e.g., `ContentID`, `MediaID`)
 3. **Prompts for confirmation** — "Do you really want to remove this file and all of its nodes?"
-4. **Stages deletion** — adds a delete entry to `.dbo/synchronize.json`
-5. **Updates app.json** — removes the `@path/to/file.metadata.json` reference from children arrays
+4. **Stages deletion** — adds a delete entry to `.app/synchronize.json`
+5. **Updates app metadata** — removes the `@path/to/file.metadata.json` reference from children arrays
 6. **Soft-deletes local files** — renames files with `__WILL_DELETE__` prefix (unless `--keep-local` or `--hard`)
 7. **After `dbo push`** — successfully deleted records have their `__WILL_DELETE__` files moved to `Trash/`
 
@@ -1485,7 +1511,7 @@ Use `--hard` to immediately delete files without the `Trash/` safety net.
 
 #### synchronize.json
 
-Pending deletions are stored in `.dbo/synchronize.json`:
+Pending deletions are stored in `.app/synchronize.json`:
 
 ```json
 {
@@ -1507,73 +1533,87 @@ The next `dbo push` processes all pending deletions before pushing file changes.
 
 ---
 
-### `dbo add`
+### `dbo adopt`
 
-Add a new file to DBO.io by creating a server record. Similar to `git add`, this registers a local file with the server.
+Create a metadata companion file for a local file, making it ready for server insertion on the next `dbo push`. This is a **local-only operation** — no server requests are made.
 
-Files matching `.dboignore` patterns are skipped — both in directory-scan mode (`dbo add .`) and single-file mode (`dbo add file.html`). Use `dbo input` to create a record for an ignored file directly.
+Files matching `.dboignore` patterns are skipped — both in directory mode (`dbo adopt ./`) and single-file mode (`dbo adopt file.html`). Use `dbo input` to create a record for an ignored file directly.
 
 #### Single file
 
 ```bash
-# Add a file (interactive metadata setup if no .metadata.json exists)
-dbo add assets/css/colors.css
+# Single file — entity inferred from directory
+dbo adopt lib/bins/app/assets/css/colors.css
+
+# Single file — explicit entity
+dbo adopt lib/bins/app/assets/css/colors.css -e content
 
-# Add with auto-accept prompts
-dbo add assets/css/colors.css -y
+# Extension with explicit column
+dbo adopt lib/extension/widget/button.html -e extension.String5
 
-# Add with ticket ID
-dbo add assets/css/colors.css --ticket abc123
+# Skip all confirmation prompts
+dbo adopt lib/bins/app/assets/css/colors.css -e content -y
 ```
 
-If the file has no companion `.metadata.json`, an interactive wizard prompts for the entity name, content column, AppID, BinID, SiteID, and Path. It then creates the metadata file and submits the insert.
+If the file lives in a recognized directory (e.g. `lib/bins/`, `lib/extension/`, `docs/`), the entity is auto-inferred via `resolveDirective()`. Otherwise, pass `-e <entity>` or follow the interactive wizard.
 
-#### Directory scan
+#### Attach to existing record (`--into`)
 
 ```bash
-# Scan current directory for un-added files
-dbo add .
-
-# Scan a specific directory
-dbo add assets/
+# Attach a second file to the same record
+dbo adopt file2.css --into file1.metadata.json -e String6
 ```
 
-Recursively finds files that either have no `.metadata.json` companion or have metadata without `_CreatedOn` (never been on the server). Lists them and prompts for confirmation before adding.
-
-When adding multiple files, the entity and column defaults from the first file are reused for subsequent files.
-
-#### After adding
+Adds `String6: "@file2.css"` to `file1.metadata.json` and appends `String6` to `_companionReferenceColumns`. No separate `file2.metadata.json` is created. Requires `-e <column>`.
 
-After a successful add, the server returns a UID which is written back to the metadata file. To populate all server-side columns (like `_CreatedOn`, `Extension`, etc.), run:
+#### Directory mode
 
 ```bash
-dbo pull -e content <uid>
+# Adopt all untracked media files in a directory
+dbo adopt lib/bins/app/assets/img/ -e media
+
+# Adopt all untracked files in the entire project as media
+dbo adopt . -e media -y
 ```
 
-#### Metadata generated by add
+Recursively finds files that have no `.metadata.json` companion (or have metadata without a UID/`_CreatedOn`). Lists them and prompts for confirmation before creating metadata. The `-e` flag is required in directory mode.
+
+#### After adopting
 
-Minimal (no optional fields provided):
+After `dbo adopt`, run `dbo push` to insert the new record(s) on the server. Push detects metadata files without a UID and submits them as new inserts.
+
+#### Metadata generated by adopt
+
+Content entity (auto-detected from `lib/bins/`):
 ```json
 {
+  "_entity": "content",
+  "_companionReferenceColumns": ["Content"],
   "Name": "colors",
-  "Path": "assets/css/colors.css",
   "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Extension": "CSS",
+  "Path": "assets/css/colors.css",
+  "Active": 1,
+  "Public": 0,
+  "BinID": 11045,
+  "AppID": 10100
 }
 ```
 
-With optional fields (only included if the user provides values during the wizard):
+Media entity:
 ```json
 {
+  "_entity": "media",
+  "_mediaFile": "@logo.png",
+  "Name": "logo",
+  "Filename": "logo.png",
+  "Extension": "png",
+  "Ownership": "App",
+  "BinID": 11048,
   "AppID": 10100,
-  "BinID": 11045,
-  "SiteID": 10061,
-  "Name": "colors",
-  "Path": "assets/css/colors.css",
-  "Content": "@colors.css",
-  "_entity": "content",
-  "_companionReferenceColumns": ["Content"]
+  "Path": "assets/img",
+  "MimeType": "image/png",
+  "FullPath": "/media/myapp/app/assets/img/logo.png"
 }
 ```
 
@@ -1581,18 +1621,15 @@ The `@colors.css` reference tells the CLI to read the file content from `colors.
 
 | Flag | Description |
 |------|-------------|
-| `<path>` | File or `.` to scan current directory |
-| `-C, --confirm <true\|false>` | Commit (default: `true`) |
-| `--ticket <id>` | Override ticket ID |
-| `--modify-key <key>` | Provide ModifyKey directly (skips interactive prompt) |
-| `--row-key <type>` | Row key type (`RowUID` or `RowID`) — `add` always uses `RowID:add1` for new records regardless |
-| `-y, --yes` | Auto-accept all prompts |
-| `--json` | Output raw JSON |
-| `--jq <expr>` | Filter JSON response |
+| `<path>` | File path, directory path, or `.` for current directory |
+| `-e, --entity <spec>` | Entity and optional column: `content`, `media`, `extension.widget`, `extension.String5`. Required in directory mode. |
+| `--into <metaPath>` | Attach file to an existing metadata record as an additional companion column (single-file only) |
+| `-y, --yes` | Skip all confirmation prompts |
+| `--domain <host>` | Override domain |
 
 #### Column filtering
 
-The `add` and `push` commands never submit these server-managed columns:
+The `push` command never submits these server-managed columns (applies to records created by `adopt`):
 - `_CreatedOn`, `_LastUpdated` — set by the server
 - `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
 - `UID` — assigned by the server on insert
@@ -1602,7 +1639,7 @@ The `add` and `push` commands never submit these server-managed columns:
 
 ### Automatic error recovery
 
-The `input`, `push`, and `add` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
+The `input` and `push` commands automatically detect recoverable server errors and prompt for missing values instead of failing immediately.
 
 #### Ticket error recovery
 
@@ -1619,7 +1656,7 @@ When the server returns a `ticket_error` (record update requires a Ticket ID), t
 
 #### Ticket suggestions
 
-When `TicketSuggestionOutput` is configured in `.dbo/config.json` (set during `dbo init`), the CLI automatically fetches relevant ticket suggestions from the server and presents them as selectable choices:
+When `TicketSuggestionOutput` is configured in `.app/config.json` (set during `dbo init`), the CLI automatically fetches relevant ticket suggestions from the server and presents them as selectable choices:
 
 ```
 ? Select a Ticket ID:
@@ -1646,7 +1683,7 @@ When the server returns a `repo_mismatch` (Ticket ID belongs to a different repo
   Skip all
 ```
 
-Ticket selections are stored in `.dbo/ticketing.local.json` for reuse across submissions. Per-record tickets are cleaned up after successful submission; the global ticket persists until explicitly cleared. The `--ticket` flag always takes precedence over stored tickets.
+Ticket selections are stored in `.app/ticketing.local.json` for reuse across submissions. Per-record tickets are cleaned up after successful submission; the global ticket persists until explicitly cleared. The `--ticket` flag always takes precedence over stored tickets.
 
 #### Ticket ID required (legacy)
 
@@ -1661,7 +1698,7 @@ The submission is then retried with `_OverrideTicketID`. To skip the prompt, pas
 
 #### Pre-submission ticket prompt
 
-When a stored ticket exists in `.dbo/ticketing.local.json`, the CLI prompts before batch submissions (`push`, `input`, `add`, `content deploy`, `deploy`):
+When a stored ticket exists in `.app/ticketing.local.json`, the CLI prompts before batch submissions (`push`, `input`, `add`, `content deploy`, `deploy`):
 
 ```
 ? Use stored Ticket ID "TICKET-123" for this submission?
@@ -1678,7 +1715,7 @@ When a stored ticket exists in `.dbo/ticketing.local.json`, the CLI prompts befo
 - **No, clear** — removes the stored `ticket_id` and proceeds without a ticket
 - **Cancel** — aborts the submission
 
-#### `.dbo/ticketing.local.json`
+#### `.app/ticketing.local.json`
 
 Stores ticket IDs for automatic application during submissions:
 
@@ -1721,14 +1758,14 @@ The ModifyKey is detected and stored during `dbo clone`. If the key wasn't store
   Cancel submission
 ```
 
-On successful reactive entry, the key is saved to `.dbo/config.json` for future use.
+On successful reactive entry, the key is saved to `.app/config.json` for future use.
 
 To bypass the interactive prompt entirely, pass `--modify-key <key>` on any submission command:
 
 ```bash
 dbo push . --modify-key mySecretKey
 dbo input -d '...' --modify-key mySecretKey
-dbo add myfile.css --modify-key mySecretKey
+dbo push myfile.css --modify-key mySecretKey
 ```
 
 #### User identity required
@@ -1800,7 +1837,7 @@ Smart behavior:
 - If plugins differ from source, prompts to upgrade to the latest version
 - Compares file hashes — unchanged files are skipped
 - Adds project-scoped plugins to `.gitignore` (source of truth is `plugins/claude/` at repo root)
-- Per-plugin scope (project or global) is stored in `.dbo/config.local.json` and remembered for future upgrades
+- Per-plugin scope (project or global) is stored in `~/.dbo/settings.json` and remembered for future upgrades
 - On re-install (e.g. after `npm install` or `npm link`), scope is inferred automatically from the global plugin registry (`~/.claude/plugins/installed_plugins.json`) or existing project installation — no prompt is shown
 - On first install with no prior preference and no existing installation, prompts for scope
 - `--global` / `--local` flags override stored preferences and update them
@@ -1809,7 +1846,7 @@ Smart behavior:
 
 ### `dbo deploy`
 
-Deploy files to DBO.io using a `.dbo/deploy_config.json` manifest or direct arguments.
+Deploy files to DBO.io using a `.app/deploy_config.json` manifest or direct arguments.
 
 ```bash
 # Deploy a named entry from the manifest
@@ -1830,7 +1867,7 @@ dbo deploy img:logo
 
 | Flag | Description |
 |------|-------------|
-| `<name>` | Deployment name from `.dbo/deploy_config.json` |
+| `<name>` | Deployment name from `.app/deploy_config.json` |
 | `--all` | Deploy all entries in the manifest |
 | `-C, --confirm <true\|false>` | Commit (default: `true`) |
 | `--ticket <id>` | Override ticket ID |
@@ -1842,9 +1879,9 @@ dbo deploy img:logo
 
 The `deploy` command includes the same automatic error recovery as `push`, `input`, and `add` — including ticket error handling, repository mismatch recovery, user identity prompts, and ModifyKey protection. When a stored ticket exists, you'll be prompted before the first submission (see [Pre-submission ticket prompt](#pre-submission-ticket-prompt)).
 
-#### `.dbo/deploy_config.json` manifest
+#### `.app/deploy_config.json` manifest
 
-Create a `.dbo/deploy_config.json` file to define named deployments:
+Create a `.app/deploy_config.json` file to define named deployments:
 
 ```json
 {
@@ -1891,10 +1928,10 @@ This replaces the curl commands typically embedded in `package.json` scripts.
 
 #### Automatic deploy config generation
 
-When you run `dbo clone` or `dbo add`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.dbo/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
+When you run `dbo clone` or `dbo adopt`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.app/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
 
 ```bash
-dbo clone   # → .dbo/deploy_config.json auto-populated with one entry per companion file
+dbo clone   # → .app/deploy_config.json auto-populated with one entry per companion file
 ```
 
 Keys are derived as `<extension>:<basename>` from the companion file path. If two files share the same key, a parent directory segment is appended to disambiguate (`css:colors` and `css:admin/colors`). Entries include `entity` and `column` from the record metadata.
@@ -1912,9 +1949,9 @@ Entries are updated automatically on re-clone (path changes are reflected in pla
 
 When running `dbo deploy` (or any submission command) inside npm scripts or piped commands where stdin is not a TTY, the CLI automatically skips all interactive prompts and uses stored credentials:
 
-- **Stored ticket** — auto-applied from `.dbo/ticketing.local.json`
-- **ModifyKey** — auto-applied from `.dbo/config.json` (`AppModifyKey`)
-- **User identity** — auto-applied from `.dbo/credentials.json`
+- **Stored ticket** — auto-applied from `.app/ticketing.local.json`
+- **ModifyKey** — auto-applied from `.app/config.json` (`AppModifyKey`)
+- **User identity** — auto-applied from `.app/credentials.json`
 
 If a required value is missing and no interactive prompt is possible, the command fails with a clear error message explaining how to set up the missing value.
 
@@ -1939,14 +1976,14 @@ To set up for non-interactive use:
 
 ## Script Hooks
 
-Script hooks let you define build and push lifecycle commands in `.dbo/scripts.json`. Hooks run automatically during `dbo push` and can also be triggered independently with `dbo build` and `dbo run`.
+Script hooks let you define build and push lifecycle commands in `.app/scripts.json`. Hooks run automatically during `dbo push` and can also be triggered independently with `dbo build` and `dbo run`.
 
 ### Configuration Files
 
 | File | Tracked | Purpose |
 |------|---------|---------|
-| `.dbo/scripts.json` | Yes | Shared hook definitions (committed to git) |
-| `.dbo/scripts.local.json` | No | Per-user overrides (gitignored) |
+| `.app/scripts.json` | Yes | Shared hook definitions (committed to git) |
+| `.app/scripts.local.json` | No | Per-user overrides (gitignored) |
 
 ### Top-level Keys
 
@@ -1956,7 +1993,7 @@ Script hooks let you define build and push lifecycle commands in `.dbo/scripts.j
 | `targets` | Per-file or per-directory hooks (highest priority) |
 | `entities` | Per-entity-type hooks (e.g., `content`, `extension.control`) |
 
-### Example `.dbo/scripts.json`
+### Example `.app/scripts.json`
 
 ```json
 {
@@ -2040,7 +2077,7 @@ dbo build
 
 ### `dbo run [script-name]`
 
-Runs a named global script from `.dbo/scripts.json` (like `npm run`). Automatically runs `pre<name>` and `post<name>` scripts if defined.
+Runs a named global script from `.app/scripts.json` (like `npm run`). Automatically runs `pre<name>` and `post<name>` scripts if defined.
 
 ```bash
 # List all available scripts
@@ -2347,7 +2384,7 @@ The `dbo` CLI writes cookies in Netscape format (same as curl's `--cookie-jar`).
 
 ```bash
 dbo login
-curl -b .dbo/cookies.txt https://my-domain.com/api/content/myUID
+curl -b .app/cookies.txt https://my-domain.com/api/content/myUID
 ```
 
 ---