docs: add installation guide and auto-version README workflow

.github/workflows/release.yml

@@ -216,18 +216,18 @@ jobs:
 
             if OS.mac?
               if Hardware::CPU.arm?
-                url "https://github.com/${{ github.repository }}/releases/download/v\${version}/kdc-v\${version}-aarch64-apple-darwin.tar.gz"
+                url "https://github.com/${{ github.repository }}/releases/download/v#{version}/kdc-v#{version}-aarch64-apple-darwin.tar.gz"
                 sha256 "${SHA_MAC_ARM64}"
               else
-                url "https://github.com/${{ github.repository }}/releases/download/v\--version/kdc-v\${version}-x86_64-apple-darwin.tar.gz"
+                url "https://github.com/${{ github.repository }}/releases/download/v#{version}/kdc-v#{version}-x86_64-apple-darwin.tar.gz"
                 sha256 "${SHA_MAC_AMD64}"
               end
             elsif OS.linux?
               if Hardware::CPU.arm?
-                url "https://github.com/${{ github.repository }}/releases/download/v\${version}/kdc-v\${version}-aarch64-unknown-linux-gnu.tar.gz"
+                url "https://github.com/${{ github.repository }}/releases/download/v#{version}/kdc-v#{version}-aarch64-unknown-linux-gnu.tar.gz"
                 sha256 "${SHA_LINUX_ARM64}"
               else
-                url "https://github.com/${{ github.repository }}/releases/download/v\${version}/kdc-v\${version}-x86_64-unknown-linux-gnu.tar.gz"
+                url "https://github.com/${{ github.repository }}/releases/download/v#{version}/kdc-v#{version}-x86_64-unknown-linux-gnu.tar.gz"
                 sha256 "${SHA_LINUX_AMD64}"
               end
             end
@@ -237,13 +237,10 @@ jobs:
             end
 
             test do
-              system "\#{bin}/kdc", "--version"
+              system "#{bin}/kdc", "--version"
             end
           end
           EOF
-
-          # Fix target download URL for macOS Intel
-          sed -i "s/v\\\\--version/v\\\\\${version}/g" dist/kdc.rb
 
           echo "Formula generated:"
           cat dist/kdc.rb

.github/workflows/update-readme-version.yml

@@ -0,0 +1,62 @@
+name: Update README Version
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to set in README (e.g. 0.2.0, without the v prefix)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  update-readme:
+    name: Bump version in README
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: get_version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # Use manual input if triggered via workflow_dispatch, otherwise strip 'v' from the release tag
+          if [ -n "${{ inputs.version }}" ]; then
+            VERSION="${{ inputs.version }}"
+          else
+            VERSION="${TAG#v}"
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+        shell: bash
+
+      - name: Replace version placeholder in README
+        env:
+          VERSION: ${{ steps.get_version.outputs.version }}
+        run: |
+          # Replace bare <VERSION> placeholders (used in URLs and text)
+          sed -i "s/<VERSION>/${VERSION}/g" README.md
+        shell: bash
+
+      - name: Commit and push updated README
+        env:
+          VERSION: ${{ steps.get_version.outputs.version }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add README.md
+          if git diff-index --quiet HEAD; then
+            echo "README already up to date, nothing to commit."
+          else
+            git commit -m "docs: bump install version to v${VERSION} in README"
+            git push origin HEAD:main
+          fi
+        shell: bash

README.md

@@ -1,21 +1,129 @@
-# KDC
+# KDC — Kubernetes Docker Commander
 
-Kubernetes Docker Commander is a project-centric DevOps terminal application.
+A project-centric DevOps terminal application for managing Docker and Kubernetes workflows from a keyboard-first TUI.
 
-The current implementation is the initial foundation slice from the design docs:
+---
 
-- project scanning
-- capability generation
-- dynamic menu generation
-- startup state
-- a keyboard-first Ratatui dashboard shell
+## Installation
 
-Run locally once Rust is installed:
+### macOS — Homebrew (recommended)
+
+If a Homebrew tap is configured, install with:
+
+```bash
+brew install KDM-cli/tap/kdc
+```
+
+Or install manually from the release tarball:
+
+```bash
+# Apple Silicon (M1/M2/M3)
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-v<VERSION>-aarch64-apple-darwin.tar.gz
+tar -xzf kdc-v<VERSION>-aarch64-apple-darwin.tar.gz
+sudo mv kdc /usr/local/bin/
+
+# Intel
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-v<VERSION>-x86_64-apple-darwin.tar.gz
+tar -xzf kdc-v<VERSION>-x86_64-apple-darwin.tar.gz
+sudo mv kdc /usr/local/bin/
+```
+
+Replace `<VERSION>` with the latest release tag (e.g. `0.1.0`). Find all releases at the [releases page](https://github.com/KDM-cli/kdc-cli/releases).
+
+---
+
+### Linux — Debian / Ubuntu (.deb)
+
+```bash
+# amd64
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc_<VERSION>_amd64.deb
+sudo dpkg -i kdc_<VERSION>_amd64.deb
+
+# arm64
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc_<VERSION>_arm64.deb
+sudo dpkg -i kdc_<VERSION>_arm64.deb
+```
+
+### Linux — Fedora / RHEL / openSUSE (.rpm)
+
+```bash
+# x86_64
+sudo rpm -i https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-<VERSION>-1.x86_64.rpm
+
+# aarch64
+sudo rpm -i https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-<VERSION>-1.aarch64.rpm
+```
+
+### Linux — tarball (any distro)
+
+```bash
+# x86_64
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-v<VERSION>-x86_64-unknown-linux-gnu.tar.gz
+tar -xzf kdc-v<VERSION>-x86_64-unknown-linux-gnu.tar.gz
+sudo mv kdc /usr/local/bin/
+
+# aarch64
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/kdc-v<VERSION>-aarch64-unknown-linux-gnu.tar.gz
+tar -xzf kdc-v<VERSION>-aarch64-unknown-linux-gnu.tar.gz
+sudo mv kdc /usr/local/bin/
+```
+
+---
+
+### Windows
+
+Download the `.zip` from the [releases page](https://github.com/KDM-cli/kdc-cli/releases/latest):
+
+```
+kdc-v<VERSION>-x86_64-pc-windows-msvc.zip
+```
+
+Extract `kdc.exe` and place it somewhere on your `PATH` (e.g. `C:\Users\<you>\bin\`).
+
+---
+
+### Verify the download (optional)
+
+Every release includes a `sha256sums.txt` file. To verify your download:
+
+```bash
+# Download the checksum file
+curl -LO https://github.com/KDM-cli/kdc-cli/releases/latest/download/sha256sums.txt
+
+# Verify (Linux/macOS)
+sha256sum --check --ignore-missing sha256sums.txt
+```
+
+---
+
+### Build from source
+
+Requires [Rust](https://rustup.rs/) (stable toolchain).
+
+```bash
+git clone https://github.com/KDM-cli/kdc-cli.git
+cd kdc-cli
+cargo build --release
+sudo mv target/release/kdc /usr/local/bin/
+```
+
+---
+
+## Quick start
+
+```bash
+kdc             # launch the TUI dashboard
+kdc scan        # scan the current directory for projects
+kdc menus       # print the generated dynamic menu tree
+```
+
+---
+
+## Development
 
 ```bash
 cargo run
 cargo run -- scan
 cargo run -- menus
 cargo test
-```
-
+```