@dboio/cli 0.6.4 → 0.6.6

package/package.json

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

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

@@ -1,13 +1,8 @@
 {
   "name": "dbo",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "DBO.io CLI integration for Claude Code",
-  "author": "DBO.io",
-  "skills": [
-    {
-      "path": "skills/cli/SKILL.md",
-      "name": "cli",
-      "description": "Execute DBO.io CLI commands"
-    }
-  ]
+  "author": {
+    "name": "DBO.io"
+  }
 }

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

@@ -0,0 +1,274 @@
+# DBO CLI Command
+
+The dbo CLI interacts with DBO.io — a database-driven application framework.
+
+**STEP 1: Check if `$ARGUMENTS` is empty or blank.**
+
+If `$ARGUMENTS` is empty — meaning the user typed just `/dbo` with nothing after it — then you MUST NOT run any bash command. Do NOT run `dbo`, `dbo --help`, or anything else. Instead, respond ONLY with this text message:
+
+---
+
+Hi there! I can help you with running dbo commands. What would you like to do?
+
+Here are the available commands:
+
+| Command   | Description                                      |
+|-----------|--------------------------------------------------|
+| init      | Initialize .dbo/ configuration                   |
+| login     | Authenticate with a DBO.io instance              |
+| logout    | Clear session                                    |
+| status    | Show config, domain, and session info            |
+| input     | Submit CRUD operations (add/edit/delete records)  |
+| output    | Query data from outputs or entities              |
+| content   | Get or deploy content                            |
+| media     | Get media files                                  |
+| upload    | Upload a file                                    |
+| message   | Send messages (email, SMS, chatbot)              |
+| pull      | Pull records to local files                      |
+| push      | Push local files back to DBO.io                  |
+| add       | Add a new file to DBO.io                         |
+| clone     | Clone an app to local project structure           |
+| diff      | Compare local files with server versions          |
+| rm        | Remove a file and stage server deletion           |
+| deploy    | Deploy via manifest                              |
+| cache     | Manage cache                                     |
+| install   | Install or upgrade CLI, plugins, Claude commands (shorthand: `i`) |
+
+Just tell me what you'd like to do and I'll help you build the right command!
+
+---
+
+Then STOP. Wait for the user to respond. Guide them step by step — asking about entities, UIDs, file paths, flags, etc. to construct the correct `dbo` command. Run `dbo status` proactively to check if the CLI is initialized and authenticated before suggesting data commands.
+
+**STEP 2: If `$ARGUMENTS` is NOT empty, run the command:**
+
+```bash
+dbo $ARGUMENTS
+```
+
+## Command Reference
+
+Available subcommands:
+- `init` — Initialize .dbo/ configuration for the current directory
+- `login` — Authenticate with a DBO.io instance
+- `logout` — Clear session
+- `status` — Show config, domain, and session info
+- `input -d '<expr>'` — CRUD operations (add/edit/delete records)
+- `output -e <entity>` — Query data from entities
+- `output <uid>` — Query custom outputs
+- `content <uid>` — Get content, `content deploy <uid> <file>` to deploy
+- `pull [uid]` — Pull records to local files (default: content entity)
+- `pull -e <entity> [uid]` — Pull from any entity
+- `push <path>` — Push local files back to DBO using metadata
+- `add <path>` — Add a new file to DBO (creates record on server)
+- `media <uid>` — Get media files
+- `upload <file>` — Upload binary files
+- `message <uid>` — Send messages (email, SMS, chatbot)
+- `cache list|refresh` — Manage cache
+- `clone [source]` — Clone an app to local project (from file or server)
+- `clone --app <name>` — Clone by app short name from server
+- `diff [path]` — Compare local files against server and selectively merge changes
+- `diff -y` — Accept all server changes without prompting
+- `diff --no-interactive` — Show diffs without prompting to accept
+- `rm <file>` — Remove a file locally and stage server deletion for next push
+- `rm <directory>` — Remove a directory, all files, and sub-directories recursively
+- `rm -f <path>` — Remove without confirmation prompts
+- `rm --keep-local <path>` — Stage server deletions without deleting local files/directories
+- `deploy [name]` — Deploy via dbo.deploy.json manifest
+- `install` (alias: `i`) — Install or upgrade CLI, plugins, or Claude commands
+- `i dbo` or `i dbo@latest` — Install/upgrade the CLI from npm
+- `i dbo@0.4.1` — Install a specific CLI version
+- `install /path/to/src` — Install CLI from local source
+- `install plugins` — Install/upgrade Claude command plugins
+- `install plugins --global` — Install plugins to `~/.claude/commands/` (shared across projects)
+- `install plugins --local` — Install plugins to `.claude/commands/` (project only)
+- `install claudecommands` — Install/upgrade Claude Code commands
+- `install claudecode` — Install Claude Code CLI + commands
+- `install --claudecommand dbo --global` — Install a specific command globally
+
+## Change Detection (pull, clone, diff)
+
+When pulling or cloning records that already exist locally, the CLI compares file modification times against the server's `_LastUpdated` timestamp. If the server has newer data, you'll be prompted with options:
+
+1. **Overwrite** — Replace local files with server version
+2. **Compare** — Show a line-by-line diff and selectively merge
+3. **Skip** — Keep local files unchanged
+4. **Overwrite all** — Accept all remaining server changes
+5. **Skip all** — Skip all remaining files
+
+Use `dbo diff [path]` to compare without pulling. Use `-y` to auto-accept all changes.
+
+## Smart Command Building
+
+When helping the user build a command interactively:
+
+1. **Check readiness first**: Run `dbo status` to see if initialized and authenticated. If not, guide them through `dbo init` and `dbo login` first.
+2. **Understand intent**: Ask what they want to do (query data, deploy a file, add a record, etc.)
+3. **Gather parameters**: Ask for the specific values needed (entity name, UID, file path, filters, etc.)
+4. **Build the command**: Construct the full `dbo` command with proper flags and syntax
+5. **Execute**: Run it and explain the results
+
+### Common workflows to suggest:
+
+- **"I want to query data"** → Guide toward `dbo output -e <entity>` with filters
+- **"I want to deploy/update a file"** → Check if `.metadata.json` exists → `dbo push` or `dbo content deploy`
+- **"I want to add a new file"** → `dbo add <path>` (will create metadata interactively)
+- **"I want to pull files from the server"** → `dbo pull` or `dbo pull -e <entity>`
+- **"I want to delete/remove a file"** → `dbo rm <file>` (stages deletion for next `dbo push`)
+- **"I want to delete a directory"** → `dbo rm <directory>` (removes all files + sub-dirs, stages bin deletions)
+- **"I want to see what's on the server"** → `dbo output -e <entity> --format json`
+- **"I need to set up this project"** → `dbo init` → `dbo login` → `dbo status`
+- **"I want to clone an app"** → `dbo clone --app <name>` or `dbo clone <local.json>`
+- **"I want to set up and clone"** → `dbo init --domain <host> --app <name> --clone`
+
+## Add Command Details
+
+`dbo add <path>` registers a new local file with the DBO server by creating an insert record.
+
+```bash
+# Add a single file (interactive metadata wizard if no .metadata.json exists)
+dbo add assets/css/colors.css
+
+# Add with auto-accept and ticket
+dbo add assets/css/colors.css -y --ticket abc123
+
+# Scan current directory for all un-added files
+dbo add .
+
+# Scan a specific directory
+dbo add assets/
+```
+
+Flags: `-C/--confirm <true|false>`, `--ticket <id>`, `-y/--yes`, `--json`, `--jq <expr>`, `-v/--verbose`, `--domain <host>`
+
+### How add works
+
+1. Checks for a companion `<basename>.metadata.json` next to the file
+2. If metadata exists with `_CreatedOn` → already on server, skips (use `push` instead)
+3. If metadata exists without `_CreatedOn` → uses it to insert the record
+4. If no metadata → interactive wizard prompts for: entity, content column, AppID, BinID, SiteID, Path
+5. Creates `.metadata.json`, submits insert to `/api/input/submit`
+6. Writes returned UID back to metadata file
+7. Suggests running `dbo pull -e <entity> <uid>` to populate all server columns
+
+### Non-interactive add (for scripting)
+
+To add without prompts, create the `.metadata.json` first, then run `dbo add <file> -y`:
+
+```json
+{
+  "Name": "colors",
+  "Path": "assets/css/colors.css",
+  "Content": "@colors.css",
+  "_entity": "content",
+  "_contentColumns": ["Content"]
+}
+```
+
+Optional fields like `AppID`, `BinID`, `SiteID` are only included if the user provides values — they have no defaults and are omitted when left blank.
+
+The `@colors.css` value means "read content from colors.css in the same directory".
+
+### Directory scan (`dbo add .`)
+
+Finds files that have no `.metadata.json` or whose metadata lacks `_CreatedOn`. Skips `.dbo/`, `.git/`, `node_modules/`, dotfiles, and `.metadata.json` files. When adding multiple files, defaults from the first file are reused.
+
+## Push Command Details
+
+`dbo push <path>` pushes local file changes back to existing DBO records using their `.metadata.json`.
+
+```bash
+dbo push assets/css/colors.css          # single file
+dbo push assets/                         # all records in directory
+dbo push assets/ --content-only          # only file content, skip metadata
+dbo push assets/ --meta-only             # only metadata columns, skip files
+dbo push assets/ -y --ticket abc123      # auto-accept + ticket
+```
+
+Flags: `-C/--confirm`, `--ticket <id>`, `--meta-only`, `--content-only`, `-y/--yes`, `--json`, `--jq`, `-v/--verbose`, `--domain`
+
+## Column Filtering (add & push)
+
+These columns are **never submitted** in add or push payloads:
+- `_CreatedOn`, `_LastUpdated` — server-managed timestamps
+- `_LastUpdatedUserID`, `_LastUpdatedTicketID` — session-provided values
+- `UID` — server-assigned on insert; used as identifier on push (not as column value)
+- `_id`, `_entity`, `_contentColumns`, `_mediaFile` — internal/metadata fields
+
+## Pull → Edit → Push/Add Workflow
+
+```bash
+# Pull existing records
+dbo pull -e content --filter 'AppID=10100'
+
+# Edit files locally, then push changes back
+dbo push assets/css/colors.css
+
+# Or add a brand new file
+dbo add assets/css/newstyle.css
+```
+
+## Clone Command Details
+
+`dbo clone` scaffolds a local project from a DBO.io app export JSON, creating directories, files, metadata, and config.
+
+```bash
+# Clone from a local JSON export file
+dbo clone /path/to/app_export.json
+
+# Clone from server by app short name (requires login)
+dbo clone --app myapp
+
+# Clone using AppShortName already in config
+dbo clone
+
+# Init + clone in one step
+dbo init --domain my-domain.com --app myapp --clone
+```
+
+Flags: `--app <name>`, `--domain <host>`, `-y/--yes`, `-v/--verbose`
+
+### What clone does
+
+1. Loads app JSON (local file, server API, or prompt)
+2. Updates `.dbo/config.json` with `AppID`, `AppUID`, `AppName`, `AppShortName`
+3. Updates `package.json` with `name`, `productName`, `description`, `homepage`, and `deploy` script
+4. Creates directory structure from `children.bin` hierarchy → saves `.dbo/structure.json`
+5. Writes content files (decodes base64) with `*.metadata.json` into bin directories
+6. Downloads media files from server via `/api/media/{uid}` with `*.metadata.json`
+7. Processes entity-dir records (`extension`, `app_version`, `data_source`, `site`, `group`, `integration`, `automation`) into project directories (`Extensions/`, `Data Sources/`, etc.) as `.metadata.json` files with optional companion content files
+8. Processes remaining entities with BinID into corresponding bin directories
+9. Saves `app.json` to project root with `@path/to/*.metadata.json` references
+
+### Placement preferences
+
+When a record has both `Path`/`FullPath` and `BinID`, clone prompts the user to choose placement. Preferences are saved to `.dbo/config.json` and reused on future clones:
+
+- `ContentPlacement`: `bin` | `path` | `ask` — for content and other entities
+- `MediaPlacement`: `bin` | `fullpath` | `ask` — for media files
+
+Pre-set these in config.json to skip prompts. `.dbo/config.json` and `.dbo/structure.json` are shared via git; `.dbo/credentials.json` and `.dbo/cookies.txt` are gitignored (per-user).
+
+### AppID awareness (add & input)
+
+After cloning, the config has an `AppID`. When running `dbo add` or `dbo input` without an AppID in the data, the CLI prompts:
+1. Yes, use AppID from config
+2. No
+3. Enter custom AppID
+
+### Init flags for clone
+
+`dbo init` now supports `--app <shortName>` and `--clone` flags to combine initialization with app cloning.
+
+## Error Handling
+
+- If the command fails with a session/authentication error, suggest: `dbo login`
+- If it fails with "No domain configured", suggest: `dbo init`
+- If a command is not found, suggest: `dbo --help`
+
+## Output
+
+When showing results:
+- Format JSON output readably
+- For pull/push/add operations, list the files created or modified
+- For query operations, summarize the row count and key fields

package/src/commands/install.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { readdir, readFile, writeFile, mkdir, access, copyFile, cp } from 'fs/promises';
+import { readdir, readFile, writeFile, mkdir, access, copyFile, cp, rm } from 'fs/promises';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -9,6 +9,10 @@ import { homedir } from 'os';
 import { log } from '../lib/logger.js';
 import { getPluginScope, setPluginScope, isInitialized, removeFromGitignore } from '../lib/config.js';
 
+const CLAUDE_PLUGINS_DIR = join(homedir(), '.claude', 'plugins');
+const PLUGIN_REGISTRY_PATH = join(CLAUDE_PLUGINS_DIR, 'installed_plugins.json');
+const PLUGIN_MARKETPLACE = 'dboio';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_ROOT = join(__dirname, '..', '..');
 const LEGACY_PLUGINS_DIR = join(__dirname, '..', 'plugins', 'claudecommands');
@@ -36,16 +40,117 @@ function getCommandsDir(scope) {
 
 /**
  * Get the target plugins directory based on scope (new directory-based format).
+ * For global scope, returns the cache path that Claude Code expects.
  * @param {'project' | 'global'} scope
  * @returns {string} Absolute path to plugins directory
  */
 function getPluginsDir(scope) {
   if (scope === 'global') {
-    return join(homedir(), '.claude', 'plugins');
+    return join(CLAUDE_PLUGINS_DIR, 'cache', PLUGIN_MARKETPLACE);
   }
   return join(process.cwd(), '.claude', 'plugins');
 }
 
+/**
+ * Get the install path for a global plugin in the cache directory.
+ * @param {string} pluginName - Plugin name
+ * @param {string} version - Plugin version
+ * @returns {string} Absolute path like ~/.claude/plugins/cache/dboio/<name>/<version>/
+ */
+function getGlobalPluginCachePath(pluginName, version) {
+  return join(CLAUDE_PLUGINS_DIR, 'cache', PLUGIN_MARKETPLACE, pluginName, version);
+}
+
+/**
+ * Read the Claude Code plugin registry (installed_plugins.json).
+ * @returns {Promise<object>} The registry object
+ */
+async function readPluginRegistry() {
+  try {
+    const content = await readFile(PLUGIN_REGISTRY_PATH, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return { version: 2, plugins: {} };
+  }
+}
+
+/**
+ * Register a plugin in Claude Code's installed_plugins.json.
+ * @param {string} pluginName - Plugin name
+ * @param {string} version - Plugin version
+ * @param {string} installPath - Absolute path to installed plugin
+ */
+async function registerPlugin(pluginName, version, installPath) {
+  const registry = await readPluginRegistry();
+  const key = `${pluginName}@${PLUGIN_MARKETPLACE}`;
+  const now = new Date().toISOString();
+
+  const existing = registry.plugins[key]?.[0];
+  if (existing) {
+    existing.installPath = installPath;
+    existing.version = version;
+    existing.lastUpdated = now;
+  } else {
+    registry.plugins[key] = [{
+      scope: 'user',
+      installPath,
+      version,
+      installedAt: now,
+      lastUpdated: now,
+    }];
+  }
+
+  await writeFile(PLUGIN_REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+}
+
+/**
+ * Unregister a plugin from Claude Code's installed_plugins.json.
+ * @param {string} pluginName - Plugin name
+ */
+async function unregisterPlugin(pluginName) {
+  const registry = await readPluginRegistry();
+  const key = `${pluginName}@${PLUGIN_MARKETPLACE}`;
+  if (registry.plugins[key]) {
+    delete registry.plugins[key];
+    await writeFile(PLUGIN_REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+  }
+}
+
+/**
+ * Extract commands/*.md from a directory plugin to ~/.claude/commands/ or .claude/commands/.
+ * This provides the /commandName shorthand alongside the /plugin:skill format.
+ * @param {string} pluginSourcePath - Path to the plugin source directory
+ * @param {'project' | 'global'} scope - Installation scope
+ * @returns {Promise<number>} Number of commands extracted
+ */
+async function extractPluginCommands(pluginSourcePath, scope) {
+  const commandsSourceDir = join(pluginSourcePath, 'commands');
+  if (!existsSync(commandsSourceDir)) return 0;
+
+  const commandsTargetDir = getCommandsDir(scope);
+  await mkdir(commandsTargetDir, { recursive: true });
+
+  let extracted = 0;
+  const files = await readdir(commandsSourceDir);
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+    const srcPath = join(commandsSourceDir, file);
+    const destPath = join(commandsTargetDir, file);
+    const srcContent = await readFile(srcPath, 'utf8');
+
+    if (await fileExists(destPath)) {
+      const destContent = await readFile(destPath, 'utf8');
+      if (fileHash(srcContent) === fileHash(destContent)) continue;
+    }
+
+    await copyFile(srcPath, destPath);
+    const label = scope === 'global' ? '~/.claude/commands/' : '.claude/commands/';
+    log.dim(`  Extracted command: ${label}${file}`);
+    extracted++;
+  }
+  return extracted;
+}
+
 /**
  * Check if a plugin source is a directory-based plugin (has .claude-plugin/).
  * @param {string} pluginPath - Path to the plugin directory
@@ -147,16 +252,23 @@ async function resolvePluginScope(pluginName, options) {
 
 /**
  * Check if plugin exists in both project and global locations.
- * Checks both legacy (.claude/commands/) and new (.claude/plugins/) paths.
+ * Checks cache path, old direct path, and legacy (.claude/commands/) paths.
  * @param {string} pluginName - Plugin name (without extension)
  * @param {string} [legacyFileName] - Legacy filename (with .md) for backward compat
  * @returns {Promise<{project: boolean, global: boolean}>}
  */
 async function checkPluginLocations(pluginName, legacyFileName) {
   const projectPlugin = join(getPluginsDir('project'), pluginName);
-  const globalPlugin = join(getPluginsDir('global'), pluginName);
   let project = await fileExists(projectPlugin);
-  let global = await fileExists(globalPlugin);
+
+  // Check global: cache path first, then old direct path
+  const registry = await readPluginRegistry();
+  const key = `${pluginName}@${PLUGIN_MARKETPLACE}`;
+  let global = !!registry.plugins[key];
+  if (!global) {
+    // Check old direct path (~/.claude/plugins/<name>/)
+    global = await fileExists(join(CLAUDE_PLUGINS_DIR, pluginName, '.claude-plugin', 'plugin.json'));
+  }
 
   // Also check legacy locations
   if (legacyFileName) {
@@ -533,25 +645,29 @@ export async function installOrUpdateClaudeCommands(options = {}) {
       }
     }
 
-    // Persist the scope preference
-    if (options.global || options.local || !await getPluginScope(plugin.name)) {
-      if (hasProject) {
-        await setPluginScope(plugin.name, targetScope);
-      } else if (targetScope === 'global') {
-        log.warn(`Cannot persist scope preference (no .dbo/ directory). Run "dbo init" first.`);
-      }
-    }
-
     if (plugin.type === 'directory') {
       // New directory-based plugin installation
-      const destDir = join(getPluginsDir(targetScope), plugin.name);
+      // Read version from plugin.json
+      const pluginMeta = JSON.parse(await readFile(join(plugin.path, '.claude-plugin', 'plugin.json'), 'utf8'));
+      const pluginVersion = pluginMeta.version || '0.0.0';
+
+      // For global scope, use the cache path and register in installed_plugins.json
+      const destDir = targetScope === 'global'
+        ? getGlobalPluginCachePath(plugin.name, pluginVersion)
+        : join(getPluginsDir('project'), plugin.name);
       const scopeLabel = targetScope === 'global' ? '~/.claude/plugins/' : '.claude/plugins/';
 
-      if (await fileExists(destDir)) {
+      // Check for existing installation (cache path or old direct path)
+      const oldDirectPath = join(CLAUDE_PLUGINS_DIR, plugin.name);
+      const existingPath = await fileExists(destDir) ? destDir
+        : (targetScope === 'global' && await fileExists(oldDirectPath)) ? oldDirectPath
+        : null;
+
+      if (existingPath) {
         // Check if upgrade needed via directory hash
         const srcHash = await directoryHash(plugin.path);
-        const destHash = await directoryHash(destDir);
-        if (srcHash === destHash) {
+        const destHash = await directoryHash(existingPath);
+        if (srcHash === destHash && existingPath === destDir) {
           upToDate++;
           continue;
         }
@@ -568,12 +684,29 @@ export async function installOrUpdateClaudeCommands(options = {}) {
           continue;
         }
 
+        await mkdir(destDir, { recursive: true });
         await cp(plugin.path, destDir, { recursive: true, force: true });
+
+        // Clean up old direct path if migrating to cache path
+        if (targetScope === 'global' && existingPath === oldDirectPath && existingPath !== destDir) {
+          await rm(oldDirectPath, { recursive: true, force: true });
+          log.dim(`  Migrated from ${oldDirectPath} to cache path`);
+        }
+
+        if (targetScope === 'global') {
+          await registerPlugin(plugin.name, pluginVersion, destDir);
+        }
+
         log.success(`Upgraded ${scopeLabel}${plugin.name}/`);
         updated++;
       } else {
         await mkdir(destDir, { recursive: true });
         await cp(plugin.path, destDir, { recursive: true });
+
+        if (targetScope === 'global') {
+          await registerPlugin(plugin.name, pluginVersion, destDir);
+        }
+
         log.success(`Installed ${scopeLabel}${plugin.name}/`);
         installed++;
 
@@ -582,19 +715,36 @@ export async function installOrUpdateClaudeCommands(options = {}) {
         }
       }
 
-      // Clean up legacy file if it exists
-      const legacyProjectPath = join(getCommandsDir('project'), legacyFileName);
-      const legacyGlobalPath = join(getCommandsDir('global'), legacyFileName);
-      if (await fileExists(legacyProjectPath)) {
-        const { unlink } = await import('fs/promises');
-        await unlink(legacyProjectPath);
-        await removeFromGitignore(`.claude/commands/${legacyFileName}`);
-        log.dim(`  Removed legacy command: .claude/commands/${legacyFileName}`);
+      // Extract commands/*.md to ~/.claude/commands/ or .claude/commands/
+      await extractPluginCommands(plugin.path, targetScope);
+
+      // Persist scope + metadata to config.local.json
+      if (hasProject && (options.global || options.local || !await getPluginScope(plugin.name))) {
+        await setPluginScope(plugin.name, {
+          scope: targetScope === 'global' ? 'user' : 'project',
+          installPath: destDir,
+          version: pluginVersion,
+        });
+      } else if (targetScope === 'global' && !hasProject) {
+        log.warn(`Cannot persist scope preference (no .dbo/ directory). Run "dbo init" first.`);
       }
-      if (await fileExists(legacyGlobalPath)) {
-        const { unlink } = await import('fs/promises');
-        await unlink(legacyGlobalPath);
-        log.dim(`  Removed legacy command: ~/.claude/commands/${legacyFileName}`);
+
+      // Clean up legacy command files (but not ones we just extracted from commands/)
+      const hasPluginCommand = existsSync(join(plugin.path, 'commands', legacyFileName));
+      if (!hasPluginCommand) {
+        const legacyProjectPath = join(getCommandsDir('project'), legacyFileName);
+        const legacyGlobalPath = join(getCommandsDir('global'), legacyFileName);
+        if (await fileExists(legacyProjectPath)) {
+          const { unlink } = await import('fs/promises');
+          await unlink(legacyProjectPath);
+          await removeFromGitignore(`.claude/commands/${legacyFileName}`);
+          log.dim(`  Removed legacy command: .claude/commands/${legacyFileName}`);
+        }
+        if (await fileExists(legacyGlobalPath)) {
+          const { unlink } = await import('fs/promises');
+          await unlink(legacyGlobalPath);
+          log.dim(`  Removed legacy command: ~/.claude/commands/${legacyFileName}`);
+        }
       }
 
       if (targetScope === 'global' && locations.project) {
@@ -644,6 +794,11 @@ export async function installOrUpdateClaudeCommands(options = {}) {
       if (targetScope === 'global' && locations.project) {
         await removeFromGitignore(`.claude/commands/${legacyFileName}`);
       }
+
+      // Persist scope for legacy plugins
+      if (hasProject && (options.global || options.local || !await getPluginScope(plugin.name))) {
+        await setPluginScope(plugin.name, targetScope);
+      }
     }
   }
 
@@ -652,7 +807,7 @@ export async function installOrUpdateClaudeCommands(options = {}) {
   if (upToDate > 0) log.dim(`${upToDate} plugin(s) already up to date.`);
   if (skipped > 0) log.dim(`${skipped} plugin(s) skipped.`);
   if (installed > 0 || updated > 0) {
-    log.info('Use /dbo:cli in Claude Code.');
+    log.info('Use /dbo in Claude Code.');
     log.warn('Note: Plugins will be available in new Claude Code sessions (restart any active session).');
   }
 }
@@ -697,24 +852,26 @@ async function installOrUpdateSpecificCommand(name, options = {}) {
     targetScope = await resolvePluginScope(pluginName, options);
   }
 
-  // Persist scope
-  if (options.global || options.local || !await getPluginScope(pluginName)) {
-    if (hasProject) {
-      await setPluginScope(pluginName, targetScope);
-    } else if (targetScope === 'global') {
-      log.warn(`Cannot persist scope preference (no .dbo/ directory). Run "dbo init" first.`);
-    }
-  }
-
   if (plugin.type === 'directory') {
     // Directory-based plugin installation
-    const destDir = join(getPluginsDir(targetScope), pluginName);
+    const pluginMeta = JSON.parse(await readFile(join(plugin.path, '.claude-plugin', 'plugin.json'), 'utf8'));
+    const pluginVersion = pluginMeta.version || '0.0.0';
+
+    const destDir = targetScope === 'global'
+      ? getGlobalPluginCachePath(pluginName, pluginVersion)
+      : join(getPluginsDir('project'), pluginName);
     const scopeLabel = targetScope === 'global' ? '~/.claude/plugins/' : '.claude/plugins/';
 
-    if (await fileExists(destDir)) {
+    // Check for existing installation (cache path or old direct path)
+    const oldDirectPath = join(CLAUDE_PLUGINS_DIR, pluginName);
+    const existingPath = await fileExists(destDir) ? destDir
+      : (targetScope === 'global' && await fileExists(oldDirectPath)) ? oldDirectPath
+      : null;
+
+    if (existingPath) {
       const srcHash = await directoryHash(plugin.path);
-      const destHash = await directoryHash(destDir);
-      if (srcHash === destHash) {
+      const destHash = await directoryHash(existingPath);
+      if (srcHash === destHash && existingPath === destDir) {
         log.success(`${pluginName} is already up to date in ${scopeLabel}`);
         return;
       }
@@ -727,11 +884,28 @@ async function installOrUpdateSpecificCommand(name, options = {}) {
       }]);
       if (!upgrade) return;
 
+      await mkdir(destDir, { recursive: true });
       await cp(plugin.path, destDir, { recursive: true, force: true });
+
+      // Clean up old direct path if migrating to cache path
+      if (targetScope === 'global' && existingPath === oldDirectPath && existingPath !== destDir) {
+        await rm(oldDirectPath, { recursive: true, force: true });
+        log.dim(`  Migrated from ${oldDirectPath} to cache path`);
+      }
+
+      if (targetScope === 'global') {
+        await registerPlugin(pluginName, pluginVersion, destDir);
+      }
+
       log.success(`Upgraded ${scopeLabel}${pluginName}/`);
     } else {
       await mkdir(destDir, { recursive: true });
       await cp(plugin.path, destDir, { recursive: true });
+
+      if (targetScope === 'global') {
+        await registerPlugin(pluginName, pluginVersion, destDir);
+      }
+
       log.success(`Installed ${scopeLabel}${pluginName}/`);
 
       if (targetScope === 'project') {
@@ -739,19 +913,36 @@ async function installOrUpdateSpecificCommand(name, options = {}) {
       }
     }
 
-    // Clean up legacy files
-    const legacyProjectPath = join(getCommandsDir('project'), legacyFileName);
-    const legacyGlobalPath = join(getCommandsDir('global'), legacyFileName);
-    if (await fileExists(legacyProjectPath)) {
-      const { unlink } = await import('fs/promises');
-      await unlink(legacyProjectPath);
-      await removeFromGitignore(`.claude/commands/${legacyFileName}`);
-      log.dim(`  Removed legacy command: .claude/commands/${legacyFileName}`);
+    // Extract commands/*.md to ~/.claude/commands/ or .claude/commands/
+    await extractPluginCommands(plugin.path, targetScope);
+
+    // Persist scope + metadata to config.local.json
+    if (hasProject && (options.global || options.local || !await getPluginScope(pluginName))) {
+      await setPluginScope(pluginName, {
+        scope: targetScope === 'global' ? 'user' : 'project',
+        installPath: destDir,
+        version: pluginVersion,
+      });
+    } else if (targetScope === 'global' && !hasProject) {
+      log.warn(`Cannot persist scope preference (no .dbo/ directory). Run "dbo init" first.`);
     }
-    if (await fileExists(legacyGlobalPath)) {
-      const { unlink } = await import('fs/promises');
-      await unlink(legacyGlobalPath);
-      log.dim(`  Removed legacy command: ~/.claude/commands/${legacyFileName}`);
+
+    // Clean up legacy command files (but not ones we just extracted from commands/)
+    const hasPluginCommand = existsSync(join(plugin.path, 'commands', legacyFileName));
+    if (!hasPluginCommand) {
+      const legacyProjectPath = join(getCommandsDir('project'), legacyFileName);
+      const legacyGlobalPath = join(getCommandsDir('global'), legacyFileName);
+      if (await fileExists(legacyProjectPath)) {
+        const { unlink } = await import('fs/promises');
+        await unlink(legacyProjectPath);
+        await removeFromGitignore(`.claude/commands/${legacyFileName}`);
+        log.dim(`  Removed legacy command: .claude/commands/${legacyFileName}`);
+      }
+      if (await fileExists(legacyGlobalPath)) {
+        const { unlink } = await import('fs/promises');
+        await unlink(legacyGlobalPath);
+        log.dim(`  Removed legacy command: ~/.claude/commands/${legacyFileName}`);
+      }
     }
 
     if (targetScope === 'global' && locations.project) {
@@ -795,6 +986,11 @@ async function installOrUpdateSpecificCommand(name, options = {}) {
     if (targetScope === 'global' && locations.project) {
       await removeFromGitignore(`.claude/commands/${legacyFileName}`);
     }
+
+    // Persist scope for legacy plugins
+    if (hasProject && (options.global || options.local || !await getPluginScope(pluginName))) {
+      await setPluginScope(pluginName, targetScope);
+    }
   }
 
   log.warn('Note: Plugins will be available in new Claude Code sessions (restart any active session).');

package/src/lib/config.js

@@ -420,38 +420,81 @@ export async function saveLocalConfig(data) {
 }
 
 /**
- * Get the stored scope for a plugin by name (without extension).
- * @param {string} pluginName - Plugin name without extension
- * @param {string} [category='claudecommands'] - Plugin category
+ * Get the stored scope for a plugin.
+ * Reads from the registry-style format: plugins["name@marketplace"][0].scope
+ * Falls back to legacy format: plugins.claudecommands.name
+ * @param {string} pluginName - Plugin name (without extension)
+ * @param {string} [marketplace='dboio'] - Marketplace identifier
  * @returns {Promise<'project' | 'global' | null>}
  */
-export async function getPluginScope(pluginName, category = 'claudecommands') {
+export async function getPluginScope(pluginName, marketplace = 'dboio') {
   const config = await loadLocalConfig();
-  return config.plugins?.[category]?.[pluginName] || null;
+  const key = `${pluginName}@${marketplace}`;
+  const entry = config.plugins?.[key]?.[0];
+  if (entry) {
+    return entry.scope === 'user' ? 'global' : entry.scope || null;
+  }
+  // Legacy fallback: plugins.claudecommands.dbo = "global"
+  const legacy = config.plugins?.claudecommands?.[pluginName];
+  return legacy || null;
 }
 
 /**
- * Set the scope for a plugin by name.
- * @param {string} pluginName - Plugin name without extension
- * @param {'project' | 'global'} scope
- * @param {string} [category='claudecommands'] - Plugin category
+ * Set plugin metadata in registry-style format.
+ * @param {string} pluginName - Plugin name
+ * @param {object} meta - Plugin metadata { scope, installPath, version }
+ * @param {string} [marketplace='dboio'] - Marketplace identifier
  */
-export async function setPluginScope(pluginName, scope, category = 'claudecommands') {
+export async function setPluginScope(pluginName, meta, marketplace = 'dboio') {
   const config = await loadLocalConfig();
   if (!config.plugins) config.plugins = {};
-  if (!config.plugins[category]) config.plugins[category] = {};
-  config.plugins[category][pluginName] = scope;
+  const key = `${pluginName}@${marketplace}`;
+  const now = new Date().toISOString();
+
+  // Support legacy callers passing just a scope string
+  if (typeof meta === 'string') {
+    meta = { scope: meta === 'global' ? 'user' : meta };
+  }
+
+  const existing = config.plugins[key]?.[0];
+  if (existing) {
+    Object.assign(existing, meta);
+    existing.lastUpdated = now;
+  } else {
+    config.plugins[key] = [{
+      scope: meta.scope || 'user',
+      installPath: meta.installPath || null,
+      version: meta.version || null,
+      installedAt: now,
+      lastUpdated: now,
+    }];
+  }
+
+  // Remove legacy entry if present
+  if (config.plugins.claudecommands?.[pluginName]) {
+    delete config.plugins.claudecommands[pluginName];
+    if (Object.keys(config.plugins.claudecommands).length === 0) {
+      delete config.plugins.claudecommands;
+    }
+  }
+
   await saveLocalConfig(config);
 }
 
 /**
- * Get all stored plugin scopes for a category.
- * Returns object mapping plugin names to their scope strings.
- * @param {string} [category='claudecommands'] - Plugin category
+ * Get all stored plugin entries.
+ * Returns object mapping registry keys to their entry arrays.
  */
-export async function getAllPluginScopes(category = 'claudecommands') {
+export async function getAllPluginScopes() {
   const config = await loadLocalConfig();
-  return config.plugins?.[category] || {};
+  const result = {};
+  if (!config.plugins) return result;
+  for (const [key, value] of Object.entries(config.plugins)) {
+    // Skip legacy category keys
+    if (typeof value === 'object' && !Array.isArray(value) && !value.scope) continue;
+    result[key] = value;
+  }
+  return result;
 }
 
 // ─── Gitignore ────────────────────────────────────────────────────────────