**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.

docs/publishing-cli.md

@@ -0,0 +1,84 @@
+# Publishing @soulcraft/brainy and @soulcraft/brainy-cli to npm
+
+This document explains how to publish both the @soulcraft/brainy and @soulcraft/brainy-cli packages to npm.
+
+## Prerequisites
+
+Before publishing, ensure you have:
+
+1. Node.js >= 24.0.0 installed
+2. An npm account with access to the @soulcraft organization
+3. Logged in to npm using `npm login`
+
+## Publishing Process
+
+The repository is set up to publish both packages together with synchronized versions. To publish the packages, follow these steps:
+
+### 1. Ensure you're in the root directory of the project
+
+```bash
+cd /path/to/brainy
+```
+
+### 2. Make sure you have the latest version of the code
+
+```bash
+git pull
+```
+
+### 3. Build and publish both packages
+
+```bash
+npm run deploy:both
+```
+
+This command will:
+- Ensure versions are in sync between both packages
+- Build the main package
+- Build the CLI
+- Verify the CLI was built successfully
+- Publish the main package to npm
+- Publish the CLI package to npm
+
+### 4. Verify the packages were published successfully
+
+After publishing, you can verify that the packages were published successfully by checking the npm registry:
+
+```bash
+npm view @soulcraft/brainy
+npm view @soulcraft/brainy-cli
+```
+
+## How It Works
+
+The publishing process uses the `scripts/publish-cli.js` script, which:
+
+1. Ensures versions are in sync by running `scripts/generate-version.js`
+2. Builds the main package with `npm run build`
+3. Builds the CLI with `npm run build:cli`
+4. Verifies the CLI was built successfully
+5. Publishes the main package with `npm publish` from the root directory
+6. Publishes the CLI package with `npm publish` from the cli-package directory
+
+The version synchronization ensures that:
+- Both packages always have the same version number
+- The CLI package's dependency on the main package is exact (not using the ^ prefix)
+- The README.md file is updated with the current version
+
+The CLI package is configured in `cli-package/package.json` with:
+- The correct package name: `@soulcraft/brainy-cli`
+- `"private": false` to allow publishing
+- `"publishConfig": { "access": "public" }` to ensure the scoped package is public
+- The necessary files in the `"files"` array
+- The correct bin configuration to make the CLI available as `brainy`
+
+## Troubleshooting
+
+If you encounter any issues during the publishing process:
+
+1. Make sure you're logged in to npm with an account that has access to the @soulcraft organization
+2. Ensure that the `dist/cli.js` file exists and has been built correctly
+3. If you get an error about the package already existing, you may need to update the version in both package.json files:
+   ```bash
+   npm version patch  # This will update both package.json files via the version script
+   ```