@dboio/cli 0.17.0 → 0.19.0

package/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:
 
@@ -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`
 
@@ -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`):
 
@@ -593,16 +595,40 @@ dbo clone -e extension --descriptor-types false       # Flat layout (no descript
 
 **`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:**
 
@@ -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`.
 
 ---
 
@@ -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
 {
@@ -1630,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:
@@ -1657,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)
 
@@ -1672,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?
@@ -1689,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:
 
@@ -1732,7 +1758,7 @@ 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:
 
@@ -1811,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
@@ -1820,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
@@ -1841,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 |
@@ -1853,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
 {
@@ -1902,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 adopt`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.dbo/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
+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.
@@ -1923,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.
 
@@ -1950,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
 
@@ -1967,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
 {
@@ -2051,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
@@ -2358,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
 ```
 
 ---

package/package.json

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