update readme

README.md

@@ -1,93 +1,73 @@
-# hns - A simple, privacy-focused speech-to-text CLI tool
-
-A simple, privacy-focused speech-to-text CLI tool that records your voice, transcribes it locally using [faster-whisper](https://github.com/SYSTRAN/faster-whisper), and copies the transcription to your clipboard. Perfect for interacting with Claude Code, VS Code, Slack, or any application where native dictation falls short.
-
-Click the image below to see the demo ⬇️ (warning: demo has sound)
-
-[![Watch Demo](https://cdn.anandprashant.com/hns/thumbnail-1.0.1.png)](https://cdn.anandprashant.com/hns/demo-1.0.1.mp4)
+<p align="center">
+  <a href=""><img src="img/hns-github-card.png" alt="hns" width="60%"></a>
+</p>
+<p align="center">
+    <em>Speech-to-text CLI. 100% local. Built for developers.</em>
+</p>
+<p align="center">
+<a href="https://pypi.org/project/hns" target="_blank">
+    <img src="https://img.shields.io/pypi/v/hns?color=%33FF33" alt="Package version">
+</a>
+<a href="https://github.com/primaprashant/hns/releases" target="_blank">
+    <img src="https://img.shields.io/github/release/primaprashant/hns?color=%33FF33" alt="Package version">
+</a>
+<a href="https://pypi.org/project/hns" target="_blank">
+    <img src="https://img.shields.io/pypi/pyversions/hns.svg?color=%33FF33" alt="Supported Python Version">
+</a>
+<a href="https://github.com/primaprashant/hns/blob/main/LICENSE" target="_blank">
+    <img src="https://img.shields.io/github/license/primaprashant/hns.svg?color=%33FF33" alt="License">
+</a>
+</p>
+
+---
+
+hns is a speech-to-text CLI tool to transcribe your voice from your microphone directly to clipboard. Integrate hns with Claude Code, Ollama, LLM, and more CLI tools for powerful workflows.
+
+`hns` transcribes your voice 100% locally using [faster-whisper](https://github.com/SYSTRAN/faster-whisper). The whisper model is downloaded automatically on first run and after that, `hns` can be used completely offline. After transcription, the text is displayed in the terminal (written to stdout) as well as automatically copied to your clipboard, ready to be pasted anywhere with `Ctrl+V` or `Cmd+V`.
+
+With `hns`, you can:
+- [Drive AI coding agents like Claude Code, Codex CLI, and Cursor CLI with your voice](https://hns-cli.dev/docs/drive-coding-agents)
+- [Dictate and get polished text for emails, Slack messages, and documents](https://hns-cli.dev/docs/voice-to-polished-text)
+- [Speak freely in a stream-of-consciousness style and get polished, coherent journal entry or note](https://hns-cli.dev/docs/effortless-daily-journaling)
+
+...and much more! Just integrate `hns` with your favorite CLI tools.
+
+## Quick Start
+
+1. Install with `uv tool install hns` and then run `hns` in your terminal.
+3. When you see `🎤 Recording...`, speak the following sentence clearly into your microphone: **"In the beginning the Universe was created. This has made a lot of people very angry and been widely regarded as a bad move"**.
+4. Press `Enter` when you're done. The transcribed text will be printed to your terminal and copied directly to your clipboard, ready to be pasted anywhere with `Ctrl+V` or `Cmd+V`.
 
 ## Highlights
 
+- **Instant Clipboard**: Transcribed text is automatically copied to your clipboard for immediate pasting
+- **Composability (The Unix Way)**: Transcription is written to stdout and progress/status messages to stderr. Easy to integrate with other CLI tools
 - **100% Local & Private**: Audio is processed entirely on your local machine. No data leaves your device
 - **Works Offline**: After the initial model download, no internet connection is required
-- **Instant Clipboard**: Transcribed text is automatically copied to your clipboard for immediate pasting
 - **Multi-Language Support**: Transcribe in any language supported by Whisper
 - **Configurable**: Choose models and languages via environment variables
-- **Focused** - Does one thing well: speech → clipboard
 - **Open Source** - MIT licensed, fully transparent
 
-## Use Cases
-
-- **Claude Code & AI Assistants**: Perfect for Claude Code or any AI interface without native dictation. Run `hns`, speak your prompt, then paste into Claude Code.
-- **Brain Dump → Structured Output**: Ramble your scattered thoughts, then paste into an LLM to organize:
-  ```sh
-  hns  # "So I'm thinking about the refactor... we need to handle auth, but also consider caching..."
-  # Paste to LLM: "Create a structured plan from these thoughts:"
-  ```
-- **Communication**: Compose Slack messages, emails, or chat responses hands-free.
-- **Note-Taking**: Quickly capture thoughts and ideas without switching from the keyboard.
-- **Accessibility**: Helpful for users who find typing difficult or painful.
-
-## Installation
-
-Install via [uv](https://github.com/astral-sh/uv) (recommended):
-```sh
-uv tool install hns
-```
-or `pipx`:
-```sh
-pipx install hns
-```
-or `pip`:
-```sh
-pip install --user hns
-```
-
-The first time you run `hns`, it will download the default Whisper model (`base`). This requires an internet connection and may take a few moments. Subsequent runs can be fully offline.
-
-## Usage
-
-### Basic Transcription
+## Docs
 
-1.  Run the command in your terminal:
-    ```sh
-    hns
-    ```
-2.  The tool will display `🎤 Recording...`. Speak into your microphone.
-3.  Press `Enter` when you have finished.
-4.  The transcribed text is automatically copied to your clipboard and printed to the console.
+- **[Overview](https://hns-cli.dev/docs/)**
+- **Get Started**
+  - [Quick Start](https://hns-cli.dev/docs/quick-start): Get `hns` up and running in less than 30 seconds.
+  - [Installation](https://hns-cli.dev/docs/installation): Different ways to install `hns`, configure it, and upgrade to the latest version.
+  - [Configuration](https://hns-cli.dev/docs/configuration): Configure `hns` to match your hardware and transcription needs. Set up Whisper models and language preferences for optimal performance.
+  - [CLI Reference](https://hns-cli.dev/docs/cli-reference): Detailed reference for all available command-line options for `hns`.
+- **Use Cases**
+  - [Overview](https://hns-cli.dev/docs/use-cases): Unlock powerful workflows by integrating `hns` with various CLI tools.
+  - [Drive AI Coding Agents With Your Voice](https://hns-cli.dev/docs/drive-coding-agents): Provide detailed, context-rich prompts to coding agents like Claude Code, Codex CLI, and Cursor CLI with your voice for faster development cycles.
+  - [Turn Your Voice Into Polished Text](https://hns-cli.dev/docs/voice-to-polished-text): Integrate `hns` with LLMs to transforms your raw dictation into polished text for emails, Slack messages, and documents, streamlining your daily communication.
+  - [Effortless Daily Journaling With Your Voice](https://hns-cli.dev/docs/effortless-daily-journaling): Speak freely in a stream-of-consciousness style and get polished, coherent journal entries or notes by integrating `hns` with LLMs.
 
-### Configuration
-
-#### Listing Models
-
-To see all available transcription models:
-```sh
-hns --list-models
-```
-
-#### Setting the Model
-
-Select a model by setting the `HNS_WHISPER_MODEL` environment variable. The default is `base`. For higher accuracy, use a larger model like `medium` or `large-v3`.
-
-```sh
-# Use the 'small' model for the current session
-export HNS_WHISPER_MODEL="small"
-hns
-```
-
-To make the change permanent, add `export HNS_WHISPER_MODEL="<model_name>"` to your shell profile (`.zshrc`, `.bash_profile`, etc.).
-
-#### Setting the Language
+## Usage
 
-By default, Whisper auto-detects the language. To force a specific language, set the `HNS_LANG` environment variable.
+![use-cases-command-examples](img/hero-command-examples-dark.png)
 
-```sh
-# Use an environment variable for Japanese
-export HNS_LANG="ja"
-hns
-```
+## Demo
 
-## License
+Watch with sound on!
 
-This project is licensed under the [MIT License](./LICENSE).
+https://github.com/user-attachments/assets/2aa3752e-bd16-4536-81bd-0679c3be3616

pyproject.toml

@@ -43,7 +43,7 @@ dev = [
 
 [tool.ruff]
 line-length = 120
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E4", "E7", "E9", "F", "I", "W", "TID", "PTH", "Q"]