Update GitHub Actions workflows and refine documentation

.github/workflows/ci.yml

@@ -18,10 +18,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js 22
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm

.github/workflows/commands-tree.yml

@@ -18,12 +18,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm

.github/workflows/dependency-audit.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 22
           cache: npm

.github/workflows/publish.yml

@@ -12,17 +12,17 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       id-token: write
     env:
       NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'
@@ -107,3 +107,11 @@ jobs:
           echo "========================================="
           npm publish --tag $NPM_TAG --access public
           echo "Successfully published $PACKAGE_NAME@$VERSION with tag: $NPM_TAG"
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag_version.outputs.tag_name }}
+          generate_release_notes: true
+          prerelease: ${{ steps.tag_version.outputs.npm_tag != 'latest' }}

README.md

@@ -1,41 +1,23 @@
-# BSH Git CLI
+# @bshsolutions/git
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![GitHub](https://img.shields.io/badge/repository-git.bsh-181717?logo=github)](https://github.com/bsh-devsolutions/git.bsh)
-
-A small **Node.js CLI** for everyday Git workflows: quick **`hello`** checks and a **`commit`** command that can install a **`commit-msg`** hook so messages stay consistent.
-
-| | |
-| --- | --- |
-| **Binary** | `git` |
-| **Package** | [`@bshsolutions/git`](https://www.npmjs.com/package/@bshsolutions/git) |
-
----
-
-## Features
+A friendly CLI for common Git workflows.
 
-- **Smoke-test friendly** — `hello` verifies the CLI runs where you need it.
-- **Structured commits** — validate messages and optionally enforce them via a Git hook.
-- **`npx`-first** — run without a global install, or `npm link` for local development.
+## Usage
 
----
+```sh
+npx @bshsolutions/git --help
+```
 
 ## Documentation
 
-docs/
-- `├──` [**Documentation home**](docs/README.md)
-- `├──` [**Setup**](docs/setup.md)
-- `├──` [**Commands**](docs/commands.md)
-- `└──` [**Commit**](docs/commit.md)
+Full guides live in the repo: [docs](docs/README.md)
 
----
+## Links
 
-## Quick start
+- [npm](https://www.npmjs.com/package/@bshsolutions/git)
+- [Repository](https://github.com/bsh-devsolutions/git.bsh)
+- [Issues](https://github.com/bsh-devsolutions/git.bsh/issues)
 
-```sh
-npm install
-npm run build
-npx @bshsolutions/git hello --name you
-```
+## License
 
-For local development, linking into other repos, and hook setup, start with [**Setup**](docs/setup.md).
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

docs/README.md

@@ -1,24 +1,15 @@
 # Documentation
 
-Reference for the **BSH Git CLI** (`git` binary, package `@bshsolutions/git`).
+Reference for the **BSH Git CLI**. Run it with **`npx @bshsolutions/git`**.
 
----
-
-## Doc tree
-
-Open a page:
-- `├──` [**Setup**](setup.md) — install, `npm run build`, `npx`, `LOG_LEVEL`, `npm link`
-- `├──` [**Commands**](commands.md) — `--help`, `init`, `commit` overview
-- `└──` [**Commit**](commit.md) — `install` / `uninstall` / `validate`, hook behavior, message shape
-
----
+## Doc's Pages
+- [**Setup**](./setup.md) (for devs)
+- [**Commands**](./commands.md)
+- [**Commands Tree**](./cmds-tree.md)
 
 ## Quick command
 
 ```sh
 npx @bshsolutions/git --help
 ```
 
----
-
-* [← Repository README](../README.md)*

docs/commands.md

@@ -1,72 +1,110 @@
 # Commands
 
-The CLI binary is **`git`** (npm package **`@bshsolutions/git`**). Examples use **`npx`** so you can copy-paste without a global install.
+Run the CLI with **`npx @bshsolutions/git`**. All examples use that form.
+
+## Global usage
 
 ```text
-Commands
-├── Built-in help
-├── Global usage
-├── init
-└── commit
-    └── (see commit.md for the subcommand tree)
+npx @bshsolutions/git [command] [options]
 ```
 
-```text
-@bshsolutions/git (conceptual)
-├── [command] [options]     (root)
-├── init
-└── commit
-    ├── install [--force]
-    ├── uninstall [--force]
-    └── validate   (alias: v)
+Help for any level:
+
+```sh
+npx @bshsolutions/git --help
+npx @bshsolutions/git commit --help
+npx @bshsolutions/git commit msg validate --help
 ```
 
----
+## Commands
+
+See the generated tree: [commands tree](./cmds-tree.md).
 
-## Built-in help
+### init
+
+Creates the project config at **`.github/bsh.json`** if it does not exist yet (merge-safe; does not overwrite an existing file). Run once per repo when you want the CLI to own local settings.
 
 ```sh
-npx @bshsolutions/git --help
+npx @bshsolutions/git init
 ```
 
----
+### rm
 
-## Global usage
+Removes **`.github/bsh.json`**. If the parent directory is empty afterward, it is removed too. No error if the file is already missing.
 
-```text
-npx @bshsolutions/git [command] [options]
+```sh
+npx @bshsolutions/git rm
 ```
 
----
+### commit
 
-## init
+**Alias:** `c` — e.g. `npx @bshsolutions/git c msg validate`.
 
-Creates **`.github/bsh.json`** with the CLI’s default configuration when that file is missing. The directory is created if needed. If the file already exists, the command does nothing (it does not overwrite).
+Parent command for structured commit tooling. Leaf commands live under **`commit msg`** (see below).
 
-### Usage
+### commit msg
 
-```text
-npx @bshsolutions/git init
+Configures and enforces commit messages using **`commit.message`** in `.github/bsh.json` (format with `{type}`, `{scope}`, `{message}` placeholders, plus allowed types and scopes). Subcommands:
+
+| Subcommand   | Alias | Role |
+| ------------ | ----- | ---- |
+| `install`    | `i`   | Add a Git `commit-msg` hook that runs validation |
+| `uninstall`  | `ui`  | Remove that hook |
+| `validate`   | `v`   | Check a message string or file |
+| `prompt`     | `p`   | Interactive type / scope / message, then `git commit` |
+
+```sh
+npx @bshsolutions/git commit msg --help
 ```
 
-The written file uses the same default shape the CLI uses when no config file is present (commit message format and logger settings).
+#### commit msg install
 
----
+- **`-f` / `--force`** — Replace an existing `commit-msg` hook. Without `--force`, the command fails if a hook file already exists and was not installed by this tool.
 
-## commit
+In an interactive terminal, you are prompted for format, types, and scopes; answers are merged into `.github/bsh.json`. A shell hook is written under **`.git/hooks/commit-msg`** that runs:
 
-Structured commits and the **`commit-msg`** hook: **`install`**, **`uninstall`**, and **`validate`**. Full behavior, flags, and hook details are in [**Commit**](commit.md).
+`npx @bshsolutions/git commit msg validate "$1"`
 
-### Usage
+Requires a Git repo with a resolvable hooks directory.
 
-```text
-npx @bshsolutions/git commit <subcommand>
+```sh
+npx @bshsolutions/git commit msg install
+npx @bshsolutions/git commit msg install --force
+```
+
+#### commit msg uninstall
+
+- **`-f` / `--force`** — Delete the hook even if it does not contain this tool’s install marker. Without `--force`, uninstall only succeeds for hooks installed by **`commit msg install`**.
+
+```sh
+npx @bshsolutions/git commit msg uninstall
+npx @bshsolutions/git commit msg uninstall --force
 ```
 
-**Alias:** `c` — for example, `npx @bshsolutions/git c validate`.
+#### commit msg validate
 
-> **Note:** Validation rules and the recommended message shape (`<type> (scope): message`) are described in `npx @bshsolutions/git commit --help` and in the [Commit](commit.md) guide.
+**Argument (optional):** `[message-or-file]` — If omitted, validation uses an empty input (and fails). If the value is an existing file path, the file contents are read; otherwise the argument is treated as the raw message.
+
+Validates the **first non-empty, non-`#` comment line** of the message as the header against your configured format, types, and scopes. Exits non-zero on failure (suitable for hooks and CI).
+
+```sh
+npx @bshsolutions/git commit msg validate "feat (app): add login"
+npx @bshsolutions/git commit msg validate /path/to/COMMIT_EDITMSG
+```
+
+#### commit msg prompt
+
+Interactive flow: prompts for each placeholder in your configured format (select or type from allowed lists), shows a preview, then optionally runs **`git commit -m "<header>"`**. Requires a TTY.
+
+- **`--dry-run`** — Print the composed header only; do not run `git commit`.
+- **`--skip-verify`** — Pass **`--no-verify`** to `git commit` (skip Git hooks).
+
+```sh
+npx @bshsolutions/git commit msg prompt
+npx @bshsolutions/git commit msg prompt --dry-run
+npx @bshsolutions/git commit msg prompt --skip-verify
+```
 
 ---
 
-* [← Setup](setup.md) · [Documentation home](README.md) · [Commit →](commit.md)*
+* [← Documentation home](README.md) · [Setup →](setup.md)*