@dboio/cli 0.13.2 → 0.15.1

package/README.md

@@ -190,6 +190,17 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 
 > **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.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.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` |
+
 #### 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.
@@ -498,6 +509,8 @@ For each entity type, the CLI prompts to choose which column becomes the filenam
 
 If any columns contain base64-encoded content, the CLI prompts to extract them as companion files. Extracted columns produce files named `<name>.<Column>.<ext>` alongside the metadata, with `@reference` entries in the metadata and a `_contentColumns` array.
 
+**Companion file naming convention:** Only `.metadata.json` files carry the `~UID` suffix (e.g. `Add-Asst-Execute-Security~wxl6ivcwfkix3zgantszjg.metadata.json`). Companion content files use the natural base name without `~UID` (e.g. `Add-Asst-Execute-Security.String16.js`). If two records share the same name within a directory, the second gets a `-1` suffix (e.g. `Add-Asst-Execute-Security-1.String16.js` with metadata `Add-Asst-Execute-Security-1~otheruid.metadata.json`). Migration 007 automatically renames legacy `~UID` companion files to the natural convention.
+
 Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
 #### Extension descriptor sub-directories
@@ -1308,6 +1321,31 @@ You can then choose to overwrite the server changes or cancel and pull first. Us
 
 ---
 
+### `dbo tag`
+
+Apply macOS Finder color tags or Linux gio emblems to companion files based on their sync status relative to the server. Tags are automatically refreshed after `dbo clone` and `dbo push`.
+
+| Tag | Color | Meaning |
+|-----|-------|---------|
+| `dbo:Synced` | 🟢 Green | File matches server — no local changes |
+| `dbo:Modified` | 🔵 Blue | Local edits not yet pushed |
+| `dbo:Untracked` | 🟡 Yellow | No metadata — not yet added with `dbo add` |
+| `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
+
+```bash
+dbo tag                  # Refresh tags for all project files
+dbo tag --clear          # Remove all dbo:* tags (preserves other Finder tags)
+dbo tag --status         # Show counts per category
+dbo tag --verbose        # Log each file and its status
+dbo tag path/to/dir      # Tag a specific file or directory subtree
+dbo tag --enable         # Enable automatic tagging after clone/push (default)
+dbo tag --disable        # Disable automatic tagging
+```
+
+Tagging is silently skipped on Windows and unsupported platforms. Only macOS (Finder color tags via `xattr`) and Linux (gio emblems) are supported. The `--clear` flag only removes `dbo:*` prefixed tags, preserving any user-applied Finder tags.
+
+---
+
 ### `dbo rm`
 
 Remove a file or directory locally and stage server deletions for the next `dbo push`. Similar to `git rm`.
@@ -1773,6 +1811,25 @@ Create a `.dbo/deploy_config.json` file to define named deployments:
 
 This replaces the curl commands typically embedded in `package.json` scripts.
 
+#### Automatic deploy config generation
+
+When you run `dbo clone` or `dbo add`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.dbo/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
+
+```bash
+dbo clone   # → .dbo/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.
+
+Once generated, you can deploy by name or by UID:
+
+```bash
+dbo deploy css:colors                   # deploy by key name
+dbo deploy cdlftyk2lkg21whojzqqoa       # deploy by UID (scans manifest values)
+```
+
+Entries are updated automatically on re-clone (path changes are reflected in place) and removed when you run `dbo rm`. When you `dbo mv` a file, the old entry is removed and a new entry is inserted with the correct key for the new path.
+
 #### Non-interactive mode (npm scripts)
 
 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:

package/bin/dbo.js

@@ -33,6 +33,7 @@ import { mvCommand } from '../src/commands/mv.js';
 import { syncCommand } from '../src/commands/sync.js';
 import { buildCommand } from '../src/commands/build.js';
 import { runCommand } from '../src/commands/run.js';
+import { tagCommand } from '../src/commands/tag.js';
 
 // First-run welcome message
 function checkFirstRun() {
@@ -95,6 +96,7 @@ program.addCommand(mvCommand);
 program.addCommand(syncCommand);
 program.addCommand(buildCommand);
 program.addCommand(runCommand);
+program.addCommand(tagCommand);
 
 // Show welcome message on first run
 checkFirstRun();

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "dbo",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"

package/plugins/claude/dbo/commands/dbo.md

@@ -1,95 +1,97 @@
-# DBO CLI Command
+---
+name: cli
+description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — use docs/ for that.
+allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo add:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
+user-invokable: true
+---
 
-Run `dbo` CLI commands for file sync, project management, and deployment.
+# DBO CLI Skill
 
-**Documentation split** — two concerns, two doc sources:
-- **CLI workflow commands** (push, pull, clone, add, rm, diff, build, deploy, install) — see `docs/dbo-cli-readme.md` for full flags, options, and behavior
-- **DBO.io REST API** (CRUD, queries, content, media, messages, cache) — see the API docs:
-  - `docs/dbo-cheat-sheet.md` — API reference, token syntax, embed system
-  - `docs/dbo-core-entities.md` — Schema catalog for all 38 core entities
-  - `docs/dbo-output-query.md` — Query output data model and parameters
-  - `docs/dbo-output-customsql.md` — CustomSQL output reference
+Run `dbo` CLI commands for local file sync, project management, and deployment.
 
-These files are in the `docs/` subdirectory relative to this plugin. When working in the repo, the API docs are at the repo root `docs/` and the CLI README is at `tools/cli/README.md`. Do NOT use CLI commands like `dbo input`, `dbo output`, `dbo content`, `dbo media`, `dbo upload`, `dbo message`, or `dbo cache` as your reference for API operations — use the REST API directly as documented in the API docs.
+## When to use this skill
 
-**STEP 1: Check if `$ARGUMENTS` is empty or blank.**
+Use this skill when the user wants to:
+- Run a local workflow command (push, pull, clone, add, rm, diff, build, deploy)
+- Set up a project (`dbo init`, `dbo login`, `dbo clone`)
+- Deploy files to the server (`dbo push`, `dbo deploy`)
 
-If `$ARGUMENTS` is empty — meaning the user typed just `/dbo` with nothing after it — then you MUST NOT run any bash command. Instead, respond with this message:
+## When NOT to use this skill
 
----
+Do NOT use this skill for direct API operations. The following CLI commands are thin wrappers around REST endpoints — use the `docs/` reference instead for the canonical API syntax:
+- `dbo input` wraps `POST /api/input/submit` — use `docs/dbo-cheat-sheet.md`
+- `dbo output` wraps `GET /api/output/` — use `docs/dbo-output-query.md`
+- `dbo content` wraps `GET /api/content/` — use `docs/dbo-cheat-sheet.md`
+- `dbo media` wraps `GET /api/media/` — use `docs/dbo-cheat-sheet.md`
+- `dbo upload` wraps `POST /api/upload/submit` — use `docs/dbo-cheat-sheet.md`
+- `dbo message` wraps `GET /api/message/` — use `docs/dbo-cheat-sheet.md`
+- `dbo cache` wraps `/api/cache/` — use `docs/dbo-cheat-sheet.md`
 
-Hi there! I can help you with running dbo commands.
+Also do NOT use this skill for:
+- **Entity schemas / column names** — use `docs/dbo-core-entities.md`
+- **Token/tag syntax** (`#{...}`, `<#_embed>`, etc.) — use `docs/dbo-cheat-sheet.md`
+- **Building server-side templates or content records** — use `docs/`
 
-| Command | Description |
-|---------|-------------|
-| init | Initialize .dbo/ configuration |
-| login | Authenticate with a DBO.io instance |
-| logout | Clear session |
-| status | Show config, domain, and session info |
-| clone | Clone an app to local project structure |
-| pull | Pull records to local files |
-| push | Push local files back to DBO.io (no args = current dir) |
-| add | Add a new file to DBO.io |
-| diff | Compare local files with server versions |
-| rm | Remove a file and stage server deletion |
-| deploy | Deploy via .dbo/deploy_config.json manifest |
-| build | Run build hooks from .dbo/scripts.json |
-| run | Run a named script from .dbo/scripts.json |
-| install | Install or upgrade CLI, plugins (shorthand: `i`) |
-
-For querying data or making direct API calls (CRUD, output, content, media, messages, cache), refer to the `docs/` directory for the REST API reference.
-
-What would you like to do?
+All doc files are bundled in the `docs/` subdirectory of this plugin (copied during npm publish). When working in the repo, the API docs are at the repo root `docs/` and the CLI README is at `tools/cli/README.md`.
 
----
+For detailed CLI command flags, options, and behavior — read `docs/dbo-cli-readme.md`.
 
-Then STOP and guide the user interactively.
+## Running commands
 
-**STEP 2: If `$ARGUMENTS` is NOT empty, run the command:**
+**If `$ARGUMENTS` is empty**, show the command table and guide interactively.
+
+**If `$ARGUMENTS` is provided**, check if command exists in the command table in the available commands (use best guess, eg: initialize => init), then on match run the command:**:
 
 ```bash
 dbo $ARGUMENTS
 ```
 
-## Quick Reference
+## Command overview
 
-### Project setup
-```bash
-dbo init --domain <host>                    # initialize
-dbo init --domain <host> --app <name> --clone  # init + clone
-dbo login                                    # authenticate
-dbo status                                   # check session
-```
+These are the local workflow commands this skill covers:
 
-### File sync workflow
-```bash
-dbo clone --app <name>                       # clone app to local
-dbo pull -e <entity> [uid]                   # pull records
-dbo push                                     # push all changes (current dir)
-dbo push <path>                              # push specific file/dir
-dbo add <path>                               # add new file to server
-dbo diff [path]                              # compare local vs server
-dbo rm <path>                                # stage deletion
-```
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize .dbo/ configuration |
+| `login` / `logout` | Authenticate / clear session |
+| `status` | Show config, domain, session info |
+| `clone` | Clone an app to local project |
+| `pull` | Pull records to local files |
+| `push` | Push local changes (default: current dir) |
+| `add` | Add a new file to DBO.io |
+| `diff` | Compare local vs server |
+| `rm` | Remove file, stage server deletion |
+| `deploy` | Deploy via .dbo/deploy_config.json manifest |
+| `build` | Run build hooks (.dbo/scripts.json) |
+| `run` | Run named script (.dbo/scripts.json) |
+| `install` | Install/upgrade CLI, plugins (alias: `i`) |
+
+## Common workflows
 
-### Build & deploy
 ```bash
-dbo build                                    # run build hooks
-dbo build <path>                             # build specific target
-dbo run [script-name]                        # run named script
-dbo deploy [name]                            # deploy via manifest
-dbo deploy --all                             # deploy all manifest entries
+# Setup
+dbo init --domain my-domain.com --app myapp --clone
+dbo login
+
+# Edit and push
+dbo push                          # push all changes in current dir
+dbo push lib/bins/app/assets/     # push specific directory
+dbo push colors.css               # push single file
+
+# Build and push (with script hooks)
+dbo build                         # run build hooks only
+dbo push                          # build + push (hooks run automatically)
+dbo push --no-build               # push without build phase
+dbo push --no-scripts             # push without any hooks
+
+# Pull
+dbo pull -e content --filter 'AppID=10100'
+
+# Add new files
+dbo add assets/css/newstyle.css
+dbo add .                         # scan for un-added files
+
+# Compare and merge
+dbo diff                          # compare all local vs server
+dbo diff -y                       # auto-accept all server changes
 ```
-
-## Interactive Guidance
-
-When helping the user build a command:
-1. Run `dbo status` to check if initialized and authenticated
-2. Ask what they want to do
-3. Gather needed parameters (entity, UID, file path, etc.)
-4. Build and execute the command
-
-## Error Recovery
-- Session/auth error: suggest `dbo login`
-- No domain configured: suggest `dbo init`
-- Command not found: suggest `dbo --help`

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

@@ -190,6 +190,17 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 
 > **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.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.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` |
+
 #### 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.
@@ -498,6 +509,8 @@ For each entity type, the CLI prompts to choose which column becomes the filenam
 
 If any columns contain base64-encoded content, the CLI prompts to extract them as companion files. Extracted columns produce files named `<name>.<Column>.<ext>` alongside the metadata, with `@reference` entries in the metadata and a `_contentColumns` array.
 
+**Companion file naming convention:** Only `.metadata.json` files carry the `~UID` suffix (e.g. `Add-Asst-Execute-Security~wxl6ivcwfkix3zgantszjg.metadata.json`). Companion content files use the natural base name without `~UID` (e.g. `Add-Asst-Execute-Security.String16.js`). If two records share the same name within a directory, the second gets a `-1` suffix (e.g. `Add-Asst-Execute-Security-1.String16.js` with metadata `Add-Asst-Execute-Security-1~otheruid.metadata.json`). Migration 007 automatically renames legacy `~UID` companion files to the natural convention.
+
 Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
 #### Extension descriptor sub-directories
@@ -1308,6 +1321,31 @@ You can then choose to overwrite the server changes or cancel and pull first. Us
 
 ---
 
+### `dbo tag`
+
+Apply macOS Finder color tags or Linux gio emblems to companion files based on their sync status relative to the server. Tags are automatically refreshed after `dbo clone` and `dbo push`.
+
+| Tag | Color | Meaning |
+|-----|-------|---------|
+| `dbo:Synced` | 🟢 Green | File matches server — no local changes |
+| `dbo:Modified` | 🔵 Blue | Local edits not yet pushed |
+| `dbo:Untracked` | 🟡 Yellow | No metadata — not yet added with `dbo add` |
+| `dbo:Trashed` | 🔴 Red | File is in the `trash/` directory |
+
+```bash
+dbo tag                  # Refresh tags for all project files
+dbo tag --clear          # Remove all dbo:* tags (preserves other Finder tags)
+dbo tag --status         # Show counts per category
+dbo tag --verbose        # Log each file and its status
+dbo tag path/to/dir      # Tag a specific file or directory subtree
+dbo tag --enable         # Enable automatic tagging after clone/push (default)
+dbo tag --disable        # Disable automatic tagging
+```
+
+Tagging is silently skipped on Windows and unsupported platforms. Only macOS (Finder color tags via `xattr`) and Linux (gio emblems) are supported. The `--clear` flag only removes `dbo:*` prefixed tags, preserving any user-applied Finder tags.
+
+---
+
 ### `dbo rm`
 
 Remove a file or directory locally and stage server deletions for the next `dbo push`. Similar to `git rm`.
@@ -1773,6 +1811,25 @@ Create a `.dbo/deploy_config.json` file to define named deployments:
 
 This replaces the curl commands typically embedded in `package.json` scripts.
 
+#### Automatic deploy config generation
+
+When you run `dbo clone` or `dbo add`, each companion file (CSS, JS, HTML, SQL, etc.) is automatically registered in `.dbo/deploy_config.json` under an `<extension>:<name>` key — no manual authoring needed:
+
+```bash
+dbo clone   # → .dbo/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.
+
+Once generated, you can deploy by name or by UID:
+
+```bash
+dbo deploy css:colors                   # deploy by key name
+dbo deploy cdlftyk2lkg21whojzqqoa       # deploy by UID (scans manifest values)
+```
+
+Entries are updated automatically on re-clone (path changes are reflected in place) and removed when you run `dbo rm`. When you `dbo mv` a file, the old entry is removed and a new entry is inserted with the correct key for the new path.
+
 #### Non-interactive mode (npm scripts)
 
 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:

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

@@ -1,6 +1,7 @@
 ---
 name: cli
 description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — use docs/ for that.
+allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo add:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
 user-invokable: true
 ---
 
@@ -39,7 +40,7 @@ For detailed CLI command flags, options, and behavior — read `docs/dbo-cli-rea
 
 **If `$ARGUMENTS` is empty**, show the command table and guide interactively.
 
-**If `$ARGUMENTS` is provided**, run:
+**If `$ARGUMENTS` is provided**, check if command exists in the command table in the available commands (use best guess, eg: initialize => init), then on match run the command:**:
 
 ```bash
 dbo $ARGUMENTS

package/src/commands/add.js

@@ -8,13 +8,14 @@ import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
 import { loadAppConfig, loadAppJsonBaseline, saveAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadConfig } from '../lib/config.js';
 import { resolveDirective, resolveTemplateCols, assembleMetadata, promptReferenceColumn, setTemplateCols, saveMetadataTemplates, loadMetadataTemplates } from '../lib/metadata-templates.js';
-import { buildUidFilename, hasUidInFilename } from '../lib/filenames.js';
+import { hasUidInFilename, buildMetaFilename, isMetadataFile } from '../lib/filenames.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { loadStructureFile, findBinByPath, BINS_DIR } from '../lib/structure.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { upsertDeployEntry } from '../lib/deploy-config.js';
 
 // ─── File type classification for auto-detection in bin directories ────────
 
@@ -673,8 +674,7 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
         // Companion file NOT renamed — only update UID in metadata and rename metadata file
         const metaDir = dirname(metaPath);
         const metaBase = basename(metaPath, '.metadata.json');
-        const newMetaBase = buildUidFilename(metaBase, returnedUID);
-        const newMetaPath = join(metaDir, `${newMetaBase}.metadata.json`);
+        const newMetaPath = join(metaDir, buildMetaFilename(metaBase, returnedUID));
 
         meta.UID = returnedUID;
 
@@ -695,9 +695,14 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
               const ref = meta[col];
               if (ref && String(ref).startsWith('@')) {
                 const fp = join(metaDir, String(ref).substring(1));
+                await upsertDeployEntry(fp, returnedUID, entity, col);
                 try { await setFileTimestamps(fp, returnedLastUpdated, returnedLastUpdated, serverTz); } catch {}
               }
             }
+            if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+              const mediaFp = join(metaDir, String(meta._mediaFile).substring(1));
+              await upsertDeployEntry(mediaFp, returnedUID, entity, 'File');
+            }
           } catch { /* non-critical */ }
         }
 
@@ -820,10 +825,10 @@ export async function findUnaddedFiles(dir, ig, referencedFiles) {
   const entries = await readdir(dir, { withFileTypes: true });
 
   // Build a set of filenames referenced by sibling metadata in this directory.
-  // This handles the ~UID naming convention: colors~uid.metadata.json → @colors.css
+  // This handles the ~UID naming convention: colors.metadata~uid.json → @colors.css
   const localRefs = new Set();
   for (const entry of entries) {
-    if (!entry.name.endsWith('.metadata.json')) continue;
+    if (!isMetadataFile(entry.name)) continue;
     try {
       const raw = await readFile(join(dir, entry.name), 'utf8');
       if (!raw.trim()) continue;
@@ -853,7 +858,7 @@ export async function findUnaddedFiles(dir, ig, referencedFiles) {
     }
 
     // Skip metadata files themselves
-    if (entry.name.endsWith('.metadata.json')) continue;
+    if (isMetadataFile(entry.name)) continue;
     // Skip ignored files
     if (ig.ignores(relPath)) continue;
 
@@ -899,7 +904,7 @@ async function _scanMetadataRefs(dir, referenced) {
       continue;
     }
 
-    if (!entry.name.endsWith('.metadata.json')) continue;
+    if (!isMetadataFile(entry.name)) continue;
 
     try {
       const raw = await readFile(fullPath, 'utf8');