From 7878f200fca5be93722abd03a9e44e1c6eff21f8 Mon Sep 17 00:00:00 2001
From: David Snelling <david@soulcraft.com>
Date: Thu, 17 Jul 2025 07:53:41 -0700
Subject: [PATCH] **docs: restructure CLI usage details and update scripts for
 clarity**

- **CLI Documentation Updates**:
  - Updated `README.md` to reflect the separation of CLI functionality into a new package: `@soulcraft/brainy-cli`.
  - Replaced inline CLI imports with instructions for installing and using `@soulcraft/brainy-cli`.
  - Clarified notes on keeping the main package lightweight by decoupling CLI functionality.

- **Script and Command Adjustments**:
  - Modified build instructions in `README.demo.md` to use `npm run build && npm run build:browser`.
  - Updated demo scripts in `package.json` to point to `/demo/index.html` instead of `/index.html`.
  - Revised style-check script in `CONTRIBUTING.md` to use `npm run check:style`.

- **Issues and Contribution Guidelines**:
  - Improved issue reporting section in `DEVELOPERS.md` with clearer guidelines and examples for bug and feature requests.

**Purpose**: These changes enhance documentation accuracy, streamline developer guidance, and ensure commands/scripts are up-to-date with current usage patterns.
---
 CONTRIBUTING.md |  2 +-
 DEVELOPERS.md   |  6 +-----
 README.demo.md  |  2 +-
 README.md       | 20 +++++---------------
 package.json    |  2 +-
 5 files changed, 9 insertions(+), 23 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7701f230..bce7f988 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -60,7 +60,7 @@ This project uses ESLint and Prettier for code formatting and style checking. Th
 
 You can check your code style by running:
 ```bash
-npm run check-style
+npm run check:style
 ```
 
 This will run all code style checks, including a specific check for semicolons.
diff --git a/DEVELOPERS.md b/DEVELOPERS.md
index e5df9498..2f41c4ec 100644
--- a/DEVELOPERS.md
+++ b/DEVELOPERS.md
@@ -168,11 +168,7 @@ These optimizations are particularly beneficial for:
 
 ## Reporting Issues
 
-We use GitHub issues to track bugs and feature requests. Please use the provided issue templates when creating a new
-issue:
-
-- [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md)
-- [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md)
+We use GitHub issues to track bugs and feature requests. When creating a new issue, please provide detailed information including steps to reproduce, expected behavior, and actual behavior for bugs, or clear use cases and benefits for feature requests.
 
 ## Code Style Guidelines
 
diff --git a/README.demo.md b/README.demo.md
index 575135ab..9ed72dbf 100644
--- a/README.demo.md
+++ b/README.demo.md
@@ -35,7 +35,7 @@ npx http-server
 If you see the error "Could not load Brainy library. Please ensure the project is built and served over HTTP", check the
 following:
 
-1. Make sure you've built the project with `npm run build:all`
+1. Make sure you've built the project with `npm run build && npm run build:browser`
 2. Ensure you're accessing the demo through HTTP (not by opening the file directly)
 3. Check your browser's console for additional error messages
 
diff --git a/README.md b/README.md
index 5fd45fb9..513baf3e 100644
--- a/README.md
+++ b/README.md
@@ -110,14 +110,9 @@ import { BrainyData } from '@soulcraft/brainy'
 
 // Minified version for production
 import { BrainyData } from '@soulcraft/brainy/min'
-
-// CLI functionality (only imported when needed)
-import '@soulcraft/brainy/cli'
 ```
 
-> **Note**: The CLI functionality (4MB) is not included in the standard import, reducing the bundle size for browser and
-> Node.js applications. The CLI is only built and loaded when explicitly imported or when using the command-line
-> interface.
+> **Note**: The CLI functionality is available as a separate package `@soulcraft/brainy-cli` to reduce the bundle size of the main package. Install it globally with `npm install -g @soulcraft/brainy-cli` to use the command-line interface.
 
 ### Browser Usage
 
@@ -417,18 +412,13 @@ brainy visualize --root <id> --depth 3
 
 ### Using the CLI in Your Code
 
-If you need to use the CLI functionality in your code, you can import it explicitly:
+The CLI functionality is available as a separate package `@soulcraft/brainy-cli`. If you need CLI functionality in your application, install the CLI package:
 
-```typescript
-// Import the CLI functionality
-import '@soulcraft/brainy/cli'
-
-// Now you can use the CLI programmatically
-// ...
+```bash
+npm install @soulcraft/brainy-cli
 ```
 
-This will only build and load the CLI when you explicitly import it, keeping your bundle size small when you don't need
-the CLI.
+Then you can use the CLI commands programmatically or through the command line interface.
 
 ### Available Commands
 
diff --git a/package.json b/package.json
index 52e844c3..8f10a3e1 100644
--- a/package.json
+++ b/package.json
@@ -54,7 +54,7 @@
     "build:browser": "BUILD_TYPE=browser rollup -c rollup.config.js",
     "build:cli": "cd cli-package && npm run build",
     "start": "node dist/unified.js",
-    "demo": "npm run build && npm run build:browser && npx http-server -o /index.html",
+    "demo": "npm run build && npm run build:browser && npx http-server -o /demo/index.html",
     "version": "node scripts/generate-version.js",
     "version:patch": "npm version patch",
     "version:minor": "npm version minor",