create-bcp-app 0.1.25 → 0.1.26

package/README.md

@@ -8,6 +8,54 @@ cd my-app
 npm run dev
 ```
 
+## Project-local BCP CLI
+
+`create-bcp-app` installs BCP Framework as a **project-local dependency**. It does not install the framework CLI globally.
+
+Generated npm scripts can use `bcp` directly because npm automatically prepends the project's `node_modules/.bin` directory to `PATH` while scripts are running:
+
+```json
+{
+  "scripts": {
+    "dev": "bcp dev",
+    "build": "bcp build",
+    "start": "bcp start",
+    "routes": "bcp routes",
+    "update": "bcp update"
+  }
+}
+```
+
+For direct PowerShell usage, invoke the local CLI through `npm exec`:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+```
+
+Typing `bcp-framework` directly in a normal PowerShell session may return `CommandNotFoundException` because PowerShell does not automatically add `node_modules/.bin` to its normal command search path.
+
+The Windows command shim can also be executed explicitly:
+
+```powershell
+.\node_modules\.bin\bcp-framework.cmd --version
+```
+
+BCP Framework publishes the `bcp-framework` alias because Microsoft SQL Server can install another Windows executable named `bcp.exe`.
+
+Recommended convention:
+
+```text
+Inside npm scripts      -> bcp ...
+Direct PowerShell usage -> npm exec -- bcp-framework ...
+```
+
+Using the project-local CLI also keeps the CLI version aligned with the exact BCP Framework dependency installed by the project.
+
 When running interactively, the generator asks:
 
 ```text
@@ -53,7 +101,7 @@ After a newer stable BCP release is published, update the project with:
 npm run update
 ```
 
-This resolves the npm `latest` release through BCP's updater, updates the exact framework dependency and refreshes the active package-manager lockfile. Use `bcp update --check` to inspect an available update without changing files.
+This resolves the npm `latest` release through BCP's updater, updates the exact framework dependency and refreshes the active package-manager lockfile. Use `bcp update --check` inside an npm script or `npm exec -- bcp-framework update --check` from PowerShell to inspect an available update without changing files.
 
 ## Generated optional setup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bcp-app",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Create a new BCP Framework application.",
   "type": "module",
   "license": "MIT",

package/template/README.md

@@ -10,7 +10,9 @@ npm run dev
 
 Open `http://localhost:3000`.
 
-## Commands
+## Project commands
+
+Generated projects use the project-local BCP Framework CLI through npm scripts:
 
 ```bash
 npm run dev
@@ -18,6 +20,65 @@ npm run routes
 npm run typecheck
 npm run build
 npm start
+npm run update
+```
+
+The generated scripts call commands such as `bcp dev`, `bcp build` and `bcp start`. This works because npm automatically adds the project's `node_modules/.bin` directory to `PATH` while an npm script is running.
+
+## Direct CLI usage
+
+BCP Framework is installed as a **project-local dependency**. It is not installed globally by `create-bcp-app`.
+
+Because of that, typing this directly in a normal PowerShell session may not work:
+
+```powershell
+bcp-framework doctor
+```
+
+PowerShell does not automatically add `node_modules/.bin` to its normal command search path.
+
+Use `npm exec` when you want to invoke the project-local CLI directly:
+
+```powershell
+npm exec -- bcp-framework --version
+npm exec -- bcp-framework doctor
+npm exec -- bcp-framework inspect
+npm exec -- bcp-framework routes
+npm exec -- bcp-framework dev
+npm exec -- bcp-framework build
+```
+
+You can also execute the Windows command shim explicitly:
+
+```powershell
+.\node_modules\.bin\bcp-framework.cmd --version
+```
+
+Using the project-local CLI is recommended because it guarantees that the CLI version matches the BCP Framework version installed by this application.
+
+### Why `bcp-framework` instead of `bcp` in PowerShell?
+
+Microsoft SQL Server can install another Windows executable named `bcp.exe`. To avoid that command-name collision, BCP Framework publishes the additional `bcp-framework` alias.
+
+Use this convention:
+
+```text
+Inside npm scripts      -> bcp ...
+Direct PowerShell usage -> npm exec -- bcp-framework ...
+```
+
+## Production
+
+Create the standalone production build:
+
+```bash
+npm run build
+```
+
+Start it with:
+
+```bash
+npm start
 ```
 
 The production build is written to `.bcp-framework/build` and runs as a standalone Node.js server.