**feat(cli, scripts): introduce CLI package and automated publishing process**

- Added a new `@soulcraft/brainy-cli` package to provide a dedicated CLI interface for the Brainy database.
- Implemented a CLI wrapper script (`cli-wrapper.js`) to manage global package execution and version handling.
- Introduced `scripts/publish-cli.js` to automate synchronized publishing of the main package and CLI, ensuring version consistency.
- Created documentation for CLI usage and publishing workflow (`publishing-cli.md`).
- Updated `package.json` to include CLI-related build and deploy scripts.
- Adjusted `README.md` to document the CLI package, usage instructions, and build separation.

This feature introduces a standalone CLI package, improves deployment automation, and enhances documentation to align with the updated architecture.

cli-package/README.md

@@ -0,0 +1,54 @@
+# @soulcraft/brainy-cli
+
+Command-line interface for the [Brainy vector graph database](https://github.com/soulcraft-research/brainy).
+
+## Installation
+
+```bash
+# Install globally
+npm install -g @soulcraft/brainy-cli
+```
+
+## Usage
+
+Once installed, you can use the `brainy` command from anywhere:
+
+```bash
+# Show help
+brainy --help
+
+# Initialize a new database
+brainy init
+
+# Add data
+brainy add "Cats are independent pets" '{"noun":"Thing","category":"animal"}'
+
+# Search
+brainy search "feline pets" --limit 5
+
+# Add relationships
+brainy addVerb id1 id2 RelatedTo '{"description":"Both are pets"}'
+
+# Visualize the graph
+brainy visualize
+brainy visualize --root <id> --depth 3
+
+# Generate random test data
+brainy generate-random-graph --noun-count 20 --verb-count 30 --clear
+```
+
+## Features
+
+- Full access to all Brainy database functionality from the command line
+- Autocomplete support for commands and options
+- Visualization of graph data
+- Import/export capabilities
+- Augmentation pipeline testing
+
+## Requirements
+
+- Node.js >= 24.0.0
+
+## License
+
+MIT

cli-package/cli-wrapper.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Wrapper Script for @soulcraft/brainy-cli
+ *
+ * This script serves as a wrapper for the Brainy CLI, ensuring that command-line arguments
+ * are properly passed to the CLI when invoked through the globally installed package.
+ */
+
+import { spawn } from 'child_process'
+import { fileURLToPath } from 'url'
+import { dirname, join } from 'path'
+import fs from 'fs'
+
+// Get the directory of the current module
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Find the main package
+const mainPackagePath = join(__dirname, 'node_modules', '@soulcraft', 'brainy')
+
+// Path to the actual CLI script in the main package
+const cliPath = join(mainPackagePath, 'dist', 'cli.js')
+
+// Check if the CLI script exists
+if (!fs.existsSync(cliPath)) {
+  console.error(`Error: CLI script not found at ${cliPath}`)
+  console.error('This is likely because the main package is not installed correctly.')
+  console.error('Please reinstall the package with:')
+  console.error('npm uninstall -g @soulcraft/brainy-cli')
+  console.error('npm install -g @soulcraft/brainy-cli --legacy-peer-deps')
+  process.exit(1)
+}
+
+// Special handling for version flags
+if (process.argv.includes('--version') || process.argv.includes('-V')) {
+  // Read version directly from package.json to ensure it's always correct
+  try {
+    const packageJsonPath = join(__dirname, 'package.json')
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+    console.log(packageJson.version)
+    process.exit(0)
+  } catch (error) {
+    console.error('Error loading version information:', error.message)
+    process.exit(1)
+  }
+}
+
+// Forward all arguments to the CLI script
+const args = process.argv.slice(2)
+
+// Check if npm is passing --force flag
+// When npm runs with --force, it sets the npm_config_force environment variable
+if (process.env.npm_config_force === 'true' && args.includes('clear') && !args.includes('--force') && !args.includes('-f')) {
+  args.push('--force')
+}
+
+const cli = spawn('node', [cliPath, ...args], { stdio: 'inherit' })
+
+cli.on('close', (code) => {
+  process.exit(code)
+})

cli-package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@soulcraft/brainy-cli",
+  "version": "0.9.16",
+  "description": "Command-line interface for the Brainy vector graph database",
+  "type": "module",
+  "bin": {
+    "brainy": "cli-wrapper.js"
+  },
+  "files": [
+    "cli-wrapper.js",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node cli-wrapper.js --version"
+  },
+  "keywords": [
+    "vector-database",
+    "hnsw",
+    "cli",
+    "command-line",
+    "graph-database"
+  ],
+  "author": "David Snelling (david@soulcraft.com)",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/soulcraft-research/brainy",
+  "bugs": {
+    "url": "https://github.com/soulcraft-research/brainy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/soulcraft-research/brainy.git"
+  },
+  "dependencies": {
+    "@soulcraft/brainy": "0.9.16"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}