@dboio/cli 0.19.2 → 0.19.7

package/README.md

@@ -157,7 +157,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
@@ -244,6 +246,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 +289,46 @@ 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`)
 
-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:
+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 |
+
+**`dbo clone`** writes all three to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description).
+
+**`dbo 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/`.
+
+**`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"]
+}
+```
+
+- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json"]`
+- **`[]`, `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`
 
@@ -460,7 +489,7 @@ 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`
+9. **Downloads media files** — classifies records into three scopes before downloading: `app` (`/media/<app>/app/...` or no FullPath — always downloaded), `user` (`/media/<app>/user/...` — opt-in, preference saved as `UserMedia` in `config.json`), and `foreign` (`/media/<other_app>/...` — silently skipped with stale metadata written). Fetches using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`. 404 errors create stale metadata to prevent re-prompting. Errors are logged to `.app/errors.log`
 10. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory (e.g., `extension/`, `data_source/`)
 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
@@ -526,6 +555,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:

package/package.json

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

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

@@ -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

@@ -43,7 +43,7 @@ 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 |
+| `clone` | Clone an app to local project structure (media filtered by scope: app/user/foreign) |
 | `pull` | Pull records to local files |
 | `push` | Push local changes to server |
 | `add` | Add a new file to DBO.io |

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

@@ -157,7 +157,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
@@ -244,6 +246,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 +289,46 @@ 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`)
 
-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:
+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 |
+
+**`dbo clone`** writes all three to the project root. If the server has no record for a file, a stub is generated automatically (`manifest.json` from app metadata, `CLAUDE.md` and `README.md` from app name/description).
+
+**`dbo 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/`.
+
+**`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"]
+}
+```
+
+- **Absent**: defaults are written on the first `dbo push` — `["CLAUDE.md", "README.md", "manifest.json"]`
+- **`[]`, `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`
 
@@ -460,7 +489,7 @@ 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`
+9. **Downloads media files** — classifies records into three scopes before downloading: `app` (`/media/<app>/app/...` or no FullPath — always downloaded), `user` (`/media/<app>/user/...` — opt-in, preference saved as `UserMedia` in `config.json`), and `foreign` (`/media/<other_app>/...` — silently skipped with stale metadata written). Fetches using a fallback chain: `FullPath` directly (`/media/{app}/{path}`) → `/dir/` route → `/api/media/{uid}`. 404 errors create stale metadata to prevent re-prompting. Errors are logged to `.app/errors.log`
 10. **Processes entity-dir records** — entities matching project directories (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) are saved as `.metadata.json` files in their corresponding directory (e.g., `extension/`, `data_source/`)
 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
@@ -526,6 +555,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:

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

@@ -0,0 +1,152 @@
+---
+name: cookbook
+description: >-
+  DBO project cookbook — operational DOs and DON'Ts for working correctly in any
+  DBO project. Load this skill when editing files, adding new features, debugging,
+  or when the white-paper provides architecture context but you need behavioral
+  rules. Covers file operations, build recipes, metadata handling, and common
+  gotchas.
+user-invokable: true
+---
+
+# DBO Project Cookbook
+
+Operational rules for working correctly in a DBO project. This is a living document — rules are added as new patterns and pitfalls are discovered.
+
+For architecture context, load the **white-paper** skill. For CLI command reference, use `/dbo`. This cookbook focuses on *how to behave* when making changes.
+
+---
+
+## DOs
+
+- **DO use UIDs, not numeric IDs, in templates.** Numeric IDs change across environments (dev → staging → prod). UIDs are stable and portable.
+- **DO run `dbo adopt` before pushing new files.** Every file in `lib/` needs a metadata companion. `dbo adopt path/to/file -e {entity}` creates one. Without it, `dbo push` won't know what server record to target.
+- **DO build from `src/` before pushing compiled assets.** Check `.app/scripts.json` for the build command. Run `npm run build` or the specific build script, then push the compiled output from `lib/`.
+- **DO check `.app/scripts.json` for build/postpush chains before manual deploys.** A file may have postpush hooks that auto-deploy dependent assets. Pushing manually with `dbo deploy` bypasses these chains.
+- **DO read the metadata file before modifying a server-tracked file.** The `.metadata~{uid}.json` companion tells you what entity, column, and record the file maps to. This context prevents wrong-target pushes.
+- **DO use `dbo diff` to verify local vs server state before bulk pushes.** Catches unexpected server-side changes that would be overwritten.
+- **DO check `app_dependencies/` for parent app patterns when building extensions.** Descriptor definitions, CSS design tokens, and JS APIs from the parent app define what's available.
+- **DO use the REST API with `.app/cookies.txt` for data operations, CLI for file operations.** The CLI handles metadata sync; the API handles data reads/writes. Don't cross these boundaries.
+- **DO check `.app/deploy_config.json` for existing shorthands before creating deploy commands.** Shorthands are auto-generated by `dbo clone` and `dbo adopt`.
+- **DO use `dbo push --confirm false` to validate before committing a push.** Dry-run catches issues without touching the server.
+
+## DON'Ts
+
+- **DON'T push `src/`, `test/`, `node_modules/`, `app_dependencies/`, or `trash/` to the server.** These are strictly local. Only `lib/` and `docs/` contents map to server records.
+- **DON'T use numeric IDs in templates.** They break across environments. Always use UIDs.
+- **DON'T create files in `lib/` without a metadata companion.** Use `dbo adopt` to assign one. Files without metadata are invisible to the CLI and won't sync.
+- **DON'T bypass `dbo push` by deploying raw files.** Push handles build scripts, metadata sync, and postpush hooks. Deploying directly skips all of that.
+- **DON'T assume a deploy shorthand exists — check `.app/deploy_config.json` first.** Not all files have shorthands. Use `dbo push` for files without one.
+- **DON'T modify vendor files in `node_modules/` or `app_dependencies/`.** These are read-only references. Vendor changes belong upstream; dependency changes belong in the source project.
+- **DON'T edit files in `app_dependencies/` directly.** They are cloned read-only mirrors. Edit in the source project and re-clone.
+- **DON'T push minified files without also pushing their unminified source.** The server tracks both. Pushing only `.min.css` leaves the content record out of sync.
+- **DON'T delete metadata files manually.** Use `dbo rm` to remove a file and its metadata together. Orphaned metadata causes ghost records.
+
+---
+
+## File Operation Recipes
+
+### Add a new file to the server
+```bash
+# 1. Create the file in the correct lib/ subdirectory
+# 2. Create metadata companion (entity is usually "content" for text, "media" for binary)
+dbo adopt lib/bins/app/assets/css/new-file.css -e content
+
+# 3. Push — inserts a new server record
+dbo push lib/bins/app/assets/css/new-file.css
+```
+
+### Modify an existing server-tracked file
+```bash
+# 1. Edit the file locally
+# 2. Push the change (metadata already exists from clone)
+dbo push lib/bins/app/assets/css/colors.css
+```
+
+### Delete a file from the server
+```bash
+# Removes the local file, its metadata, and the server record
+dbo rm lib/bins/app/assets/css/old-file.css
+```
+
+### Rename or move a file
+There is no rename command. Instead:
+```bash
+# 1. Create the new file with the desired name/location
+# 2. Adopt it as a new record
+dbo adopt lib/bins/app/assets/css/renamed.css -e content
+# 3. Push the new file
+dbo push lib/bins/app/assets/css/renamed.css
+# 4. Remove the old file
+dbo rm lib/bins/app/assets/css/old-name.css
+```
+
+### Move a file between bins
+Same as rename — the bin is determined by the directory path. Moving to a new directory means a new BinID, which requires a new record.
+
+---
+
+## Build Recipes
+
+### CSS: SASS source → compiled → minified
+```bash
+# Build compiles src/sass/ → lib/bins/.../css/ and minifies
+npm run build
+# Or run the specific target from .app/scripts.json:
+sass src/sass/colors:lib/bins/app/assets/css
+csso lib/bins/app/assets/css/colors.css --output lib/bins/app/assets/css/colors.min.css
+```
+Then push both the unminified and minified versions.
+
+### JS: Rollup bundle
+```bash
+# Bundles ES6 modules from src/ into lib/bins/.../js/app.min.js
+rollup --config src/rollup.config.mjs
+# Then push
+dbo push lib/bins/app/assets/js/app.min.js
+```
+
+### When does push auto-compile?
+It doesn't. `dbo push` triggers **postpush** scripts (defined in `.app/scripts.json` under `targets.{file}.postpush`), but these are for deploying *dependent* assets, not for compiling. Always build first, then push.
+
+### Check what builds exist
+```bash
+# Read the scripts config
+cat .app/scripts.json
+```
+Look at `targets.{file}.build` for compile commands and `targets.{file}.postpush` for post-push deploy chains.
+
+---
+
+## Gotchas
+
+### Metadata mismatch after manual file creation
+**Symptom:** `dbo push` says "no changes detected" for a file you just created.
+**Cause:** No metadata companion exists. The CLI doesn't track unregistered files.
+**Fix:** Run `dbo adopt path/to/file -e {entity}` first.
+
+### Postpush chain didn't fire
+**Symptom:** You pushed a JS file but the documentation deploy didn't happen.
+**Cause:** You used `dbo deploy` instead of `dbo push`. Deploy bypasses postpush hooks.
+**Fix:** Use `dbo push` for files with postpush chains, or manually run the postpush commands.
+
+### Content and media records out of sync
+**Symptom:** CSS looks wrong on the server even though you pushed the file.
+**Cause:** You pushed only the content record but not the media companion (or vice versa).
+**Fix:** Push both — check `deploy_config.json` for paired `{name}` and `{name}_media` entries.
+
+### Wrong entity type on adopt
+**Symptom:** Pushed file lands in unexpected server location.
+**Cause:** Used wrong `-e` flag on `dbo adopt` (e.g., `-e media` for a text file).
+**Fix:** Remove with `dbo rm`, re-adopt with correct entity type, re-push.
+
+### Extension files not picked up
+**Symptom:** New extension file doesn't appear in the app.
+**Cause:** Extension files follow strict naming: `{Name}.{ContentColumnName}.{ext}` with metadata companion.
+**Fix:** Verify the file name matches the pattern and the descriptor type exists in `app_dependencies/`.
+
+---
+
+## Project-Specific Overlays
+
+Individual DBO projects may provide an additional conventions file at `docs/Operator_Claude.md` (or equivalent). When present, load it alongside this cookbook for project-specific DOs, DON'Ts, and patterns. When the project is a dependency of another app, the overlay appears at `app_dependencies/{app}/docs/{App}_Claude.md`.

package/plugins/claude/track/commands/install.md

@@ -1,5 +1,5 @@
 ---
-name: install
+name: install-track-changelog
 description: Install the Track changelog integration — creates ~/.claude/track-changelog login script.
 user-invokable: true
 allowed-tools: Write, Bash(chmod:*)

package/src/commands/adopt.js

@@ -3,7 +3,7 @@ import { readFile, writeFile, stat, mkdir } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
 import { log } from '../lib/logger.js';
 import { loadIgnore } from '../lib/ignore.js';
-import { loadAppConfig, loadAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference } from '../lib/config.js';
+import { loadAppConfig, loadAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadRootContentFiles } from '../lib/config.js';
 import {
   resolveDirective, resolveTemplateCols, assembleMetadata,
   promptReferenceColumn, getTemplateCols, setTemplateCols,
@@ -11,7 +11,7 @@ import {
 } from '../lib/metadata-schema.js';
 import { loadStructureFile, findBinByPath, BINS_DIR } from '../lib/structure.js';
 import { isMetadataFile } from '../lib/filenames.js';
-import { findUnaddedFiles, MIME_TYPES, seedMetadataTemplate, detectDocumentationFile, detectManifestFile } from '../lib/insert.js';
+import { findUnaddedFiles, MIME_TYPES, seedMetadataTemplate, detectDocumentationFile } from '../lib/insert.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 
 export const adoptCommand = new Command('adopt')
@@ -79,6 +79,15 @@ function parseEntitySpec(spec, metadataSchema) {
   return { entity, descriptor: null, column: sub };
 }
 
+/**
+ * Metadata templates for known root content files (mirrors push.js ROOT_FILE_TEMPLATES).
+ */
+const ROOT_FILE_TEMPLATES = {
+  'manifest.json': { Extension: 'JSON', Public: 1, Active: 1, Title: 'PWA Manifest' },
+  'CLAUDE.md':     { Extension: 'MD',   Public: 0, Active: 1, Title: 'Claude Code Instructions' },
+  'README.md':     { Extension: 'MD',   Public: 1, Active: 1, Title: 'README' },
+};
+
 /**
  * Build entity-specific metadata for a file in or outside lib/bins/.
  */
@@ -144,6 +153,61 @@ async function buildBinMetadata(filePath, entity, appConfig, structure) {
 async function adoptSingleFile(filePath, entityArg, options) {
   const ig = await loadIgnore();
   const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  const fileName = basename(filePath);
+
+  // --- Root content file check (before ignore): CLAUDE.md, README.md, manifest.json, etc. ---
+  // These files live at the project root but their metadata goes in lib/bins/app/.
+  // They bypass the dboignore check and entity inference.
+  const rootFiles = await loadRootContentFiles();
+  if (rootFiles.includes(fileName) && relPath === fileName) {
+    const appConfig = await loadAppConfig();
+    const structure = await loadStructureFile();
+    const appBin = findBinByPath('app', structure);
+    const binsAppDir = join(process.cwd(), BINS_DIR, 'app');
+    const ext = extname(fileName).replace('.', '').toUpperCase() || 'TXT';
+    const stem = basename(fileName, extname(fileName));
+
+    const metaFilename = `${stem}.metadata.json`;
+    const metaPath = join(binsAppDir, metaFilename);
+
+    // Check for existing metadata
+    let existingMeta = null;
+    try { existingMeta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
+    if (existingMeta) {
+      if (existingMeta.UID || existingMeta._CreatedOn) {
+        log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+        return;
+      }
+      if (!options.yes) {
+        const inquirer = (await import('inquirer')).default;
+        const { overwrite } = await inquirer.prompt([{
+          type: 'confirm', name: 'overwrite',
+          message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+          default: false,
+        }]);
+        if (!overwrite) return;
+      }
+    }
+
+    const tmpl = ROOT_FILE_TEMPLATES[fileName] || { Extension: ext, Public: 0, Active: 1, Title: fileName };
+    const meta = {
+      _entity: 'content',
+      _companionReferenceColumns: ['Content'],
+      ...tmpl,
+      Content: `@/${fileName}`,
+      Path: fileName,
+      Name: fileName,
+    };
+    if (appBin) meta.BinID = appBin.binId;
+    if (appConfig.AppID) meta.AppID = appConfig.AppID;
+
+    await mkdir(binsAppDir, { recursive: true });
+    await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    log.success(`Created ${metaFilename} for ${fileName}`);
+    log.dim(`  Run "dbo push" to insert this record on the server.`);
+    return;
+  }
+
   if (ig.ignores(relPath)) {
     log.dim(`Skipped (dboignored): ${relPath}`);
     return;
@@ -152,7 +216,6 @@ async function adoptSingleFile(filePath, entityArg, options) {
   const dir = dirname(filePath);
   const ext = extname(filePath);
   const base = basename(filePath, ext);
-  const fileName = basename(filePath);
 
   // Check for existing metadata
   const metaPath = join(dir, `${base}.metadata.json`);
@@ -204,16 +267,6 @@ async function adoptSingleFile(filePath, entityArg, options) {
 
   const appConfig = await loadAppConfig();
 
-  // --- Special case: manifest.json ---
-  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
-  if (rel.toLowerCase() === 'manifest.json') {
-    const manifestResult = await detectManifestFile(filePath);
-    if (manifestResult) {
-      log.success(`Created manifest metadata at ${manifestResult.metaPath}`);
-      return;
-    }
-  }
-
   // --- content or media entities: build entity-specific metadata ---
   if ((entity === 'content' || entity === 'media') && !column) {
     const structure = await loadStructureFile();
@@ -238,6 +291,7 @@ async function adoptSingleFile(filePath, entityArg, options) {
       Descriptor: 'documentation',
       Name: docBase,
     };
+    if (appConfig.AppID) docMeta.AppID = appConfig.AppID;
     const contentCol = 'String10';
     docMeta[contentCol] = `@/${relPath}`;
     docMeta._companionReferenceColumns = [contentCol];

package/src/commands/clone.js

@@ -1,9 +1,9 @@
 import { Command } from 'commander';
-import { readFile, writeFile, appendFile, mkdir, access, readdir, rename, stat, utimes } from 'fs/promises';
+import { readFile, writeFile, appendFile, mkdir, access, readdir, rename, stat, utimes, unlink } from 'fs/promises';
 import { join, basename, extname, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, updateConfigUserMedia, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement, loadRootContentFiles } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, SCAFFOLD_DIRS, ENTITY_DIR_NAMES, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES, EXTENSION_DESCRIPTORS_DIR, EXTENSION_UNSUPPORTED_DIR, DOCUMENTATION_DIR, buildDescriptorMapping, saveDescriptorMapping, loadDescriptorMapping, resolveExtensionSubDir, resolveEntityDirPath, resolveFieldValue } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { buildUidFilename, buildContentFileName, buildMetaFilename, isMetadataFile, parseMetaFilename, stripUidFromFilename, hasUidInFilename } from '../lib/filenames.js';
@@ -19,6 +19,7 @@ import { runPendingMigrations } from '../lib/migrations.js';
 import { upsertDeployEntry } from '../lib/deploy-config.js';
 import { syncDependencies, parseDependenciesColumn } from '../lib/dependencies.js';
 import { sep } from 'path';
+import { installOrUpdateClaudeCommands } from './install.js';
 
 /** True when cwd is inside app_dependencies/ (dependency checkout clone). */
 function isDependencyCheckout() {
@@ -359,6 +360,26 @@ export function resolveMediaPaths(record, structure) {
   return { dir, filename: companionFilename, metaPath };
 }
 
+/**
+ * Classify a media record based on its FullPath relative to the app short name.
+ *
+ * Returns:
+ *   'app'     — /media/<appShortName>/app/... or no FullPath (assumed app media)
+ *   'user'    — /media/<appShortName>/user/...
+ *   'foreign' — /media/<other_app>/... (belongs to a different app entirely)
+ */
+function classifyMediaRecord(record, appShortName) {
+  const fp = record.FullPath;
+  if (!fp || !appShortName) return 'app';
+  const normalized = fp.startsWith('/') ? fp.slice(1) : fp;
+  // Must start with media/<appShortName>/
+  const appPrefix = `media/${appShortName.toLowerCase()}/`;
+  if (!normalized.toLowerCase().startsWith(appPrefix)) return 'foreign';
+  const rest = normalized.slice(appPrefix.length);
+  if (rest.toLowerCase().startsWith('user/')) return 'user';
+  return 'app';
+}
+
 /**
  * Extract path components for entity-dir records.
  * Simplified from processEntityDirEntries() for collision detection.
@@ -1392,9 +1413,10 @@ export async function performClone(source, options = {}) {
     );
   }
 
-  // Step 5a: Write manifest.json to project root (skip for dependency checkouts)
+  // Step 5a: Write root content files (manifest.json, CLAUDE.md, README.md, etc.) to project root.
+  // Also fixes the duplicate bug: relocates companions from lib/bins/app/ to root and rewrites metadata.
   if ((!entityFilter || entityFilter.has('content')) && !isDependencyCheckout()) {
-    await writeManifestJson(appJson, contentRefs);
+    await writeRootContentFiles(appJson, contentRefs);
   }
 
   // Step 5b: Process media → download binary files + metadata (skip rejected records)
@@ -1480,6 +1502,29 @@ export async function performClone(source, options = {}) {
   if (!options.pullMode) {
     log.dim('  Run "dbo login" to authenticate, then "dbo push" to deploy changes');
   }
+
+  // Offer to install Claude Code plugins on fresh clone (not pull, not dependency checkout)
+  if (!options.pullMode && !isDependencyCheckout()) {
+    const pluginsDir = join(process.cwd(), '.claude', 'plugins');
+    let pluginsAlreadyInstalled = false;
+    try {
+      const entries = await readdir(pluginsDir);
+      pluginsAlreadyInstalled = entries.length > 0;
+    } catch { /* directory doesn't exist */ }
+
+    if (!pluginsAlreadyInstalled) {
+      const inquirer = (await import('inquirer')).default;
+      const { install } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'install',
+        message: 'Install Claude Code plugins for this project? (adds /dbo and /track commands)',
+        default: true,
+      }]);
+      if (install) {
+        await installOrUpdateClaudeCommands({ local: true });
+      }
+    }
+  }
 }
 
 /**
@@ -2751,16 +2796,86 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
 async function processMediaEntries(mediaRecords, structure, options, config, appShortName, serverTz, skipUIDs = new Set(), resolvedFilenames = new Map()) {
   if (!mediaRecords || mediaRecords.length === 0) return [];
 
+  // ── Step 0: Classify records by path scope ──────────────────────────────
+  // foreign = /media/<other_app>/... (not this app — never download)
+  // user    = /media/<appShortName>/user/... (opt-in via UserMedia config)
+  // app     = /media/<appShortName>/app/... or no FullPath (always download)
+  const foreignRecords = [];
+  const userRecords = [];
+  const appRecords = [];
+
+  for (const record of mediaRecords) {
+    if (skipUIDs.has(record.UID)) continue;
+    const cls = classifyMediaRecord(record, appShortName);
+    if (cls === 'foreign') foreignRecords.push(record);
+    else if (cls === 'user') userRecords.push(record);
+    else appRecords.push(record);
+  }
+
+  // Silently write stale metadata for foreign records so they are never
+  // re-prompted on future clones. No download is attempted.
+  const foreignRefs = [];
+  for (const record of foreignRecords) {
+    const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
+    const resolvedName = resolvedFilenames.get(record.UID);
+    const effectiveMetaPath = resolvedName
+      ? join(scanDir, buildMetaFilename(resolvedName, String(record.UID || record._id || 'untitled')))
+      : scanMetaPath;
+    if (!(await fileExists(effectiveMetaPath))) {
+      const staleMeta = { _entity: 'media', _foreignApp: true };
+      for (const [k, v] of Object.entries(record)) {
+        if (k !== 'children') staleMeta[k] = v;
+      }
+      try {
+        await mkdir(scanDir, { recursive: true });
+        await writeFile(effectiveMetaPath, JSON.stringify(staleMeta, null, 2) + '\n');
+        if (serverTz && (record._CreatedOn || record._LastUpdated)) {
+          await setFileTimestamps(effectiveMetaPath, record._CreatedOn, record._LastUpdated, serverTz);
+        }
+      } catch { /* non-critical */ }
+    }
+    foreignRefs.push({ uid: record.UID, metaPath: effectiveMetaPath });
+  }
+  if (foreignRecords.length > 0) {
+    log.dim(`  Skipped ${foreignRecords.length} foreign media file(s) (not in /media/${appShortName || '?'}/)`);
+  }
+
+  // ── User media: prompt once if preference is unset ───────────────────────
+  // config.UserMedia: true = include, false = skip, undefined = not yet asked
+  let includeUserMedia = config.UserMedia ?? null;
+  if (userRecords.length > 0 && includeUserMedia === null && !options.yes) {
+    const inquirer = (await import('inquirer')).default;
+    const exampleFile = userRecords[0].Filename || userRecords[0].Name || 'user file';
+    const { includeUser } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'includeUser',
+      message: `App has ${userRecords.length} user media file(s) (e.g. "${exampleFile}"). Download user media? (saves preference)`,
+      default: false,
+    }]);
+    includeUserMedia = includeUser;
+    await updateConfigUserMedia(includeUserMedia);
+  } else if (userRecords.length > 0 && options.yes && includeUserMedia === null) {
+    // Non-interactive: default to false, save preference
+    includeUserMedia = false;
+    await updateConfigUserMedia(false);
+  }
+
+  if (!includeUserMedia && userRecords.length > 0) {
+    log.dim(`  Skipped ${userRecords.length} user media file(s) (UserMedia=false)`);
+  }
+
+  // Active records = app media + user media (if opted in)
+  const activeRecords = includeUserMedia ? [...appRecords, ...userRecords] : appRecords;
+
   // Track stale records (404s) for cleanup prompt
   const staleRecords = [];
 
   // Pre-scan: determine which media files actually need downloading
   // (new files or files with newer server timestamps)
   const needsDownload = [];
-  const upToDateRefs = [];
+  const upToDateRefs = [...foreignRefs];
 
-  for (const record of mediaRecords) {
-    if (skipUIDs.has(record.UID)) continue;
+  for (const record of activeRecords) {
 
     const { metaPath: scanMetaPath, dir: scanDir } = resolveMediaPaths(record, structure);
     // Use collision-resolved filename for metadata path when available (e.g. "_media" suffix)
@@ -2791,7 +2906,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   }
 
   if (needsDownload.length === 0) {
-    log.dim(`  All ${mediaRecords.length} media file(s) up to date`);
+    log.dim(`  All ${activeRecords.length} media file(s) up to date`);
     return upToDateRefs;
   }
 
@@ -2804,7 +2919,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const { download } = await inquirer.prompt([{
       type: 'confirm',
       name: 'download',
-      message: `${needsDownload.length} media file(s) need to be downloaded (${mediaRecords.length - needsDownload.length} up to date). Attempt download now?`,
+      message: `${needsDownload.length} media file(s) need to be downloaded (${activeRecords.length - needsDownload.length} up to date). Attempt download now?`,
       default: true,
     }]);
     canDownload = download;
@@ -2833,9 +2948,9 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   let downloaded = 0;
   let failed = 0;
 
-  log.info(`Downloading ${mediaRecords.length} media file(s)...`);
+  log.info(`Downloading ${activeRecords.length} media file(s)...`);
 
-  for (const record of mediaRecords) {
+  for (const record of activeRecords) {
     const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
 
     if (skipUIDs.has(record.UID)) {
@@ -4089,53 +4204,136 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
 }
 
 /**
- * Write manifest.json to project root.
- * If a manifest content record was cloned from the server, use its Content value.
- * Otherwise, generate from appJson values (empty strings for missing fields).
+ * Write root content files (manifest.json, CLAUDE.md, README.md, etc.) to the project root.
+ *
+ * For each filename in rootContentFiles:
+ *   - If a matching content record exists in contentRefs: relocate the companion from
+ *     lib/bins/app/<filename> to the project root, delete the bins/app copy, and rewrite
+ *     the metadata to use Content: "@/<filename>" (root-relative). This fixes the duplicate
+ *     bug where processRecord always writes companions next to the metadata file.
+ *   - If no server record: generate a fallback stub at the project root.
+ */
+async function writeRootContentFiles(appJson, contentRefs) {
+  const rootFiles = await loadRootContentFiles();
+  if (!rootFiles.length) return;
+
+  for (const filename of rootFiles) {
+    const handled = await _writeRootFile(filename, appJson, contentRefs);
+    if (!handled) {
+      await _generateRootFileStub(filename, appJson);
+    }
+  }
+}
+
+/**
+ * Find the content record for a root file and relocate its companion to the project root.
+ * Returns true if handled, false if no matching record was found.
  */
-async function writeManifestJson(appJson, contentRefs) {
-  // 1. Search contentRefs for a manifest content record
+async function _writeRootFile(filename, appJson, contentRefs) {
+  const filenameLower = filename.toLowerCase();
+  const stemLower = filenameLower.includes('.') ? filenameLower.slice(0, filenameLower.lastIndexOf('.')) : filenameLower;
+  const extLower = filenameLower.includes('.') ? filenameLower.slice(filenameLower.lastIndexOf('.') + 1) : '';
+
   for (const ref of contentRefs) {
     let meta;
+    try { meta = JSON.parse(await readFile(ref.metaPath, 'utf8')); } catch { continue; }
+
+    // Match by Name+Extension, or by Content @reference, or by Path
+    const metaName = (meta.Name || '').toLowerCase();
+    const metaExt = (meta.Extension || '').toLowerCase();
+    const metaContent = String(meta.Content || '');
+    const metaPath2 = String(meta.Path || '');
+    const contentRef = metaContent.startsWith('@/') ? metaContent.slice(2)
+      : metaContent.startsWith('@') ? metaContent.slice(1)
+      : null;
+
+    const matchByName = metaName.startsWith(stemLower) && metaExt === extLower;
+    const matchByContent = contentRef && contentRef.toLowerCase() === filenameLower;
+    const matchByPath = metaPath2.replace(/^\//, '').toLowerCase() === filenameLower;
+
+    if (!matchByName && !matchByContent && !matchByPath) continue;
+
+    // Found a matching record — read companion content from bins/app dir
+    const metaDir = dirname(ref.metaPath);
+    const localCompanion = join(metaDir, filename);
+    let content;
     try {
-      meta = JSON.parse(await readFile(ref.metaPath, 'utf8'));
-    } catch { continue; }
-
-    const name = (meta.Name || '').toLowerCase();
-    const ext = (meta.Extension || '').toLowerCase();
-    if (name.startsWith('manifest') && ext === 'json') {
-      // Found manifest — read content file and write to project root
-      const contentRef = meta.Content;
-      if (contentRef && String(contentRef).startsWith('@')) {
-        const refFile = String(contentRef).substring(1);
-        // Try root-relative first, then sibling of metadata, then project root fallback
-        const candidates = refFile.startsWith('/')
-          ? [join(process.cwd(), refFile)]
-          : [join(dirname(ref.metaPath), refFile), join(process.cwd(), refFile)];
-        let content;
-        for (const candidate of candidates) {
-          try {
-            content = await readFile(candidate, 'utf8');
-            break;
-          } catch { /* try next */ }
-        }
-        if (content !== undefined) {
-          await writeFile('manifest.json', content);
-          log.dim('  manifest.json written to project root (from server content)');
-        } else {
-          log.warn(`  Could not find manifest.json companion file`);
-        }
+      content = await readFile(localCompanion, 'utf8');
+    } catch {
+      // Companion may already be at root (re-clone scenario) or never written (no Content on server)
+      try { content = await readFile(join(process.cwd(), filename), 'utf8'); } catch { /* nothing */ }
+    }
+
+    if (content !== undefined) {
+      await writeFile(join(process.cwd(), filename), content);
+      log.dim(`  ${filename} written to project root (from server content)`);
+
+      // Delete stale companion in bins/app if it exists there
+      if (localCompanion !== join(process.cwd(), filename)) {
+        try { await unlink(localCompanion); } catch { /* already gone or at root */ }
       }
-      return;
+    } else {
+      log.warn(`  Could not find companion file for ${filename}`);
     }
+
+    // Rewrite metadata: root-relative Content reference
+    try {
+      const updated = { ...meta, Content: `@/${filename}` };
+      if (!updated._companionReferenceColumns) updated._companionReferenceColumns = ['Content'];
+      await writeFile(ref.metaPath, JSON.stringify(updated, null, 2) + '\n');
+    } catch { /* non-critical */ }
+
+    return true;
   }
 
-  // 2. No manifest content record — generate from appJson values
+  return false; // No server record found
+}
+
+/**
+ * Generate a fallback stub for a root content file when the server has no record.
+ * Skips if the file already exists at the project root.
+ */
+async function _generateRootFileStub(filename, appJson) {
+  const rootPath = join(process.cwd(), filename);
+  try { await access(rootPath); return; } catch { /* doesn't exist — generate */ }
+
+  const appName = appJson.Name || appJson.ShortName || '';
+  const description = appJson.Description || '';
+  const filenameLower = filename.toLowerCase();
+
+  if (filenameLower === 'manifest.json') {
+    await _generateManifestFallback(appJson);
+    return;
+  }
+
+  if (filenameLower === 'claude.md') {
+    const stub = `# ${appName}\n\nAdd Claude Code instructions for this project here.\n`;
+    await writeFile(rootPath, stub);
+    log.dim(`  CLAUDE.md generated at project root (stub)`);
+    return;
+  }
+
+  if (filenameLower === 'readme.md') {
+    const parts = [`# ${appName}`];
+    if (description) parts.push('', description);
+    parts.push('');
+    await writeFile(rootPath, parts.join('\n'));
+    log.dim(`  README.md generated at project root (stub)`);
+    return;
+  }
+
+  // Unknown file type — no stub generated
+}
+
+/**
+ * Generate manifest.json at project root from appJson values.
+ * Preserves existing behaviour from the old writeManifestJson fallback.
+ */
+async function _generateManifestFallback(appJson) {
   const shortName = appJson.ShortName || '';
   const appName = appJson.Name || '';
   const description = appJson.Description || '';
 
-  // Find background_color from extension children (widget descriptor matching ShortName)
   let bgColor = '#ffffff';
   if (shortName) {
     const extensions = appJson.children?.extension || [];
@@ -4167,7 +4365,7 @@ async function writeManifestJson(appJson, contentRefs) {
     icons: [],
   };
 
-  await writeFile('manifest.json', JSON.stringify(manifest, null, 2) + '\n');
+  await writeFile(join(process.cwd(), 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
   log.dim('  manifest.json generated at project root (from app metadata)');
 }
 

package/src/commands/push.js

@@ -6,7 +6,7 @@ import { buildInputBody, checkSubmitErrors, getSessionUserOverride } from '../li
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal, addDeleteEntry } from '../lib/config.js';
+import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal, addDeleteEntry, loadRootContentFiles } from '../lib/config.js';
 import { mergeScriptsConfig, resolveHooks, buildHookEnv, runBuildLifecycle, runPushLifecycle } from '../lib/scripts.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
@@ -343,6 +343,33 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
       metaPath = found;
       try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
     }
+    if (!meta) {
+      // Last resort: project-wide search for cross-directory @reference.
+      // Handles cases where the companion file is in a different directory from its metadata
+      // (e.g. docs/Operator_Claude.md → lib/extension/Documentation/Operator_Claude.metadata~uid.json).
+      const absoluteFilePath = filePath.startsWith('/') ? filePath : join(process.cwd(), filePath);
+      const ig = await loadIgnore();
+      const allMetaFiles = await findMetadataFiles(process.cwd(), ig);
+      for (const candidatePath of allMetaFiles) {
+        try {
+          const candidateMeta = JSON.parse(await readFile(candidatePath, 'utf8'));
+          const metaDir = dirname(candidatePath);
+          const cols = [...(candidateMeta._companionReferenceColumns || candidateMeta._contentColumns || [])];
+          if (candidateMeta._mediaFile) cols.push('_mediaFile');
+          for (const col of cols) {
+            const ref = candidateMeta[col];
+            if (!ref || !String(ref).startsWith('@')) continue;
+            const resolved = resolveAtReference(String(ref).substring(1), metaDir);
+            if (resolved === absoluteFilePath) {
+              metaPath = candidatePath;
+              meta = candidateMeta;
+              break;
+            }
+          }
+        } catch { /* skip unreadable */ }
+        if (meta) break;
+      }
+    }
     if (!meta) {
       // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
       // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
@@ -399,70 +426,130 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
   }
   // ── End script hooks ────────────────────────────────────────────────
 
-  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  const success = await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
+  if (success) {
+    const baseline = await loadAppJsonBaseline();
+    if (baseline) {
+      await updateBaselineAfterPush(baseline, [{ meta, metaPath, changedColumns: null }]);
+    }
+  }
+  return success;
 }
 /**
- * Ensure manifest.json at project root has companion metadata in lib/bins/app/.
- * Only creates metadata if manifest.json exists at root AND no existing metadata
- * anywhere in the project already references @/manifest.json (prevents duplicates).
+ * Metadata templates for known root content files.
+ * Keyed by filename (case-sensitive). Unknown files in rootContentFiles
+ * get a sensible derived template (extension from name, Public: 0).
  */
-async function ensureManifestMetadata() {
-  // Check if manifest.json exists at project root
-  try {
-    await access(join(process.cwd(), 'manifest.json'));
-  } catch {
-    return; // No manifest.json — nothing to do
-  }
+const ROOT_FILE_TEMPLATES = {
+  'manifest.json': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'JSON',
+    Public: 1,
+    Active: 1,
+    Title: 'PWA Manifest',
+  },
+  'CLAUDE.md': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'MD',
+    Public: 0,
+    Active: 1,
+    Title: 'Claude Code Instructions',
+  },
+  'README.md': {
+    _entity: 'content',
+    _companionReferenceColumns: ['Content'],
+    Extension: 'MD',
+    Public: 1,
+    Active: 1,
+    Title: 'README',
+  },
+};
+
+/**
+ * For each filename in rootContentFiles, ensure a companion metadata file
+ * exists in lib/bins/app/. Skips if the file is absent at root or if metadata
+ * already tracks it. Creates metadata with Content: "@/<filename>" so push
+ * always reads from the project root.
+ */
+async function ensureRootContentFiles() {
+  const rootFiles = await loadRootContentFiles();
+  if (!rootFiles.length) return;
 
-  // Scan the entire project for any metadata file that already references manifest.json.
-  // This prevents creating duplicates when the metadata lives in an unexpected location.
-  // Check both @/manifest.json (root-relative) and @manifest.json (local) references,
-  // as well as Path: manifest.json which indicates a server record for this file.
   const ig = await loadIgnore();
   const allMeta = await findMetadataFiles(process.cwd(), ig);
+
+  // Build a set of already-tracked filenames from existing metadata.
+  // Also strip stale fields (e.g. Descriptor) from content-entity root file metadata.
+  const tracked = new Set();
   for (const metaPath of allMeta) {
     try {
       const raw = await readFile(metaPath, 'utf8');
       const parsed = JSON.parse(raw);
-      if (parsed.Content === '@/manifest.json' || parsed.Content === '@manifest.json') return;
-      if (parsed.Path === 'manifest.json' || parsed.Path === '/manifest.json') return;
+      const content = parsed.Content || '';
+      const path = parsed.Path || '';
+      // Detect both @/filename (root-relative) and @filename (local) references
+      const refName = content.startsWith('@/') ? content.slice(2)
+        : content.startsWith('@') ? content.slice(1)
+        : null;
+      if (refName) tracked.add(refName);
+      if (path) tracked.add(path.replace(/^\//, ''));
+
+      // Clean up stale Descriptor field: content entities never have Descriptor.
+      // This fixes metadata written by an earlier buggy version of the tool.
+      if (parsed._entity === 'content' && parsed.Descriptor !== undefined) {
+        const cleaned = { ...parsed };
+        delete cleaned.Descriptor;
+        await writeFile(metaPath, JSON.stringify(cleaned, null, 2) + '\n');
+        log.dim(`  Removed stale Descriptor field from ${basename(metaPath)}`);
+      }
     } catch { /* skip unreadable */ }
   }
 
-  // No existing metadata references manifest.json — create one
   const appConfig = await loadAppConfig();
   const structure = await loadStructureFile();
   const appBin = findBinByPath('app', structure);
-
   const binsAppDir = join(process.cwd(), BINS_DIR, 'app');
-  await mkdir(binsAppDir, { recursive: true });
 
-  const meta = {
-    _entity: 'content',
-    _companionReferenceColumns: ['Content'],
-    Content: '@/manifest.json',
-    Path: 'manifest.json',
-    Name: 'manifest.json',
-    Extension: 'JSON',
-    Public: 1,
-    Active: 1,
-    Title: 'PWA Manifest',
-  };
-
-  if (appBin) meta.BinID = appBin.binId;
-  if (appConfig.AppID) meta.AppID = appConfig.AppID;
-
-  const metaPath = join(binsAppDir, 'manifest.metadata.json');
-  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
-  log.info('Auto-created manifest.metadata.json for manifest.json');
+  for (const filename of rootFiles) {
+    // Skip if file doesn't exist at project root
+    try { await access(join(process.cwd(), filename)); } catch { continue; }
+    // Skip if already tracked by existing metadata
+    if (tracked.has(filename)) continue;
+
+    const tmpl = ROOT_FILE_TEMPLATES[filename] || {
+      _entity: 'content',
+      _companionReferenceColumns: ['Content'],
+      Extension: (filename.includes('.') ? filename.split('.').pop().toUpperCase() : 'TXT'),
+      Public: 0,
+      Active: 1,
+      Title: filename,
+    };
+
+    const meta = {
+      ...tmpl,
+      Content: `@/${filename}`,
+      Path: filename,
+      Name: filename,
+    };
+    if (appBin) meta.BinID = appBin.binId;
+    if (appConfig.AppID) meta.AppID = appConfig.AppID;
+
+    await mkdir(binsAppDir, { recursive: true });
+    const stem = filename.replace(/\.[^.]+$/, '');
+    const metaFilename = `${stem}.metadata.json`;
+    await writeFile(join(binsAppDir, metaFilename), JSON.stringify(meta, null, 2) + '\n');
+    log.info(`Auto-created ${metaFilename} for ${filename}`);
+  }
 }
 
 /**
  * Push all records found in a directory (recursive)
  */
 async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID', deletedCount = 0) {
-  // Auto-create manifest.metadata.json if manifest.json exists at root without companion metadata
-  await ensureManifestMetadata();
+  // Auto-create metadata for root content files (manifest.json, CLAUDE.md, README.md, etc.)
+  await ensureRootContentFiles();
 
   // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
   // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
@@ -1378,12 +1465,14 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     if (editResults.length > 0) {
       const updated = editResults[0]._LastUpdated || editResults[0].LastUpdated;
       if (updated) {
+        // Always update _LastUpdated in memory and on disk (required for baseline sync
+        // even when ServerTimezone is not configured)
+        meta._LastUpdated = updated;
+        await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
         const config = await loadConfig();
         const serverTz = config.ServerTimezone;
         if (serverTz) {
-          // Update metadata _LastUpdated and set file mtime
-          meta._LastUpdated = updated;
-          await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+          // Set file mtimes to server timestamp (requires timezone for correct conversion)
           await setFileTimestamps(metaPath, meta._CreatedOn, updated, serverTz);
           // Update content file mtime too
           const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];

package/src/lib/config.js

@@ -173,6 +173,20 @@ export async function updateConfigWithApp({ AppID, AppUID, AppName, AppShortName
   await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
 }
 
+/**
+ * Persist the UserMedia preference to .app/config.json.
+ * @param {boolean} value - true = download user media, false = skip
+ */
+export async function updateConfigUserMedia(value) {
+  await mkdir(projectDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  existing.UserMedia = value;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
 // ─── Dependency helpers ───────────────────────────────────────────────────
 
 /**
@@ -1070,6 +1084,39 @@ export async function loadScriptsLocal() {
   }
 }
 
+// ─── Root Content Files ───────────────────────────────────────────────────────
+
+const ROOT_CONTENT_FILES_DEFAULTS = ['CLAUDE.md', 'README.md', 'manifest.json'];
+
+/**
+ * Load rootContentFiles from .app/config.json.
+ * If the key is absent, writes the defaults and returns them.
+ * If the key is [], false, or null, returns [] (disabled).
+ */
+export async function loadRootContentFiles() {
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (!('rootContentFiles' in existing)) {
+    await saveRootContentFiles(ROOT_CONTENT_FILES_DEFAULTS);
+    return ROOT_CONTENT_FILES_DEFAULTS;
+  }
+  const val = existing.rootContentFiles;
+  if (!val || (Array.isArray(val) && val.length === 0)) return [];
+  return Array.isArray(val) ? val : [];
+}
+
+/**
+ * Persist rootContentFiles to .app/config.json.
+ * Pass [] to disable root content file tracking.
+ */
+export async function saveRootContentFiles(list) {
+  await mkdir(projectDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  existing.rootContentFiles = list;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
 // ─── Tag Config ───────────────────────────────────────────────────────────────
 
 /**