diff --git a/www/apps/docs/content/b/subcommands/completion.mdx b/www/apps/docs/content/b/subcommands/completion.mdx
index 86b977f..47da341 100644
--- a/www/apps/docs/content/b/subcommands/completion.mdx
+++ b/www/apps/docs/content/b/subcommands/completion.mdx
@@ -1,36 +1,36 @@
 ---
-description: "Generate shell completion scripts for b CLI"
+description: "Generate the autocompletion script for the specified shell."
 ---
 
 # b completion
 
-The `b completion` command generates shell completion scripts for the b CLI, enabling tab completion for commands, flags, and arguments in your shell.
+Generate the autocompletion script for `b` for the specified shell. See each sub-command's help for details on how to use the generated script.
 
-## Synopsis
+## Usage
 
 ```bash
-# Generate completion script for your shell
-b completion [bash|zsh|fish|powershell]
-
-# Source the completion script in your current shell session
-source <(b completion bash)  # for bash
+b completion [command]
 ```
 
-## Description
-
-The `completion` command generates shell completion scripts that provide command-line completion for b CLI. This allows you to use the Tab key to automatically complete commands, subcommands, flags, and arguments, making the CLI more user-friendly and efficient.
+## Available Commands
 
-## Available Shells
+| Command      | Description                                  |
+|--------------|----------------------------------------------|
+| `bash`       | Generate the autocompletion script for bash  |
+| `fish`       | Generate the autocompletion script for fish  |
+| `powershell` | Generate the autocompletion script for powershell |
+| `zsh`        | Generate the autocompletion script for zsh   |
 
-Completion is available for the following shells:
+## Flags
 
-- **bash**: For Bash shell users
-- **zsh**: For Zsh shell users
-- **fish**: For Fish shell users
-- **powershell**: For PowerShell users
+| Flag     | Description           |
+|----------|-----------------------|
+| `-h`, `--help` | help for completion   |
 
 ## Installation
 
+To use shell completion, you need to generate the script for your shell and source it.
+
 ### Bash
 
 Add the following to your `~/.bashrc` or `~/.bash_profile`:
@@ -40,6 +40,16 @@ Add the following to your `~/.bashrc` or `~/.bash_profile`:
 source <(b completion bash)
 ```
 
+For a better completion experience with bash, consider installing the `bash-completion` package:
+
+```bash
+# On macOS with Homebrew
+brew install bash-completion
+
+# On Ubuntu/Debian
+sudo apt-get install bash-completion
+```
+
 ### Zsh
 
 Add the following to your `~/.zshrc`:
@@ -51,6 +61,8 @@ if [ $commands[b] ]; then
 fi
 ```
 
+If you're using Oh My Zsh, the completion should work out of the box after installation.
+
 ### Fish
 
 Save the completion script to your Fish completions directory:
@@ -74,23 +86,17 @@ b completion powershell | Out-String | Invoke-Expression
 
 ## Examples
 
-### Generate Completion Script
+### Generate and Save Completion Script
 
 ```bash
-# Generate bash completion script
+# Generate bash completion script and save it
 b completion bash > /etc/bash_completion.d/b
 
-# Generate zsh completion script
+# Generate zsh completion script for Oh My Zsh
 b completion zsh > "${fpath[1]}/_b"
-
-# Generate fish completion script
-b completion fish > ~/.config/fish/completions/b.fish
-
-# Generate PowerShell completion script
-b completion powershell > ~/.b-completion.ps1
 ```
 
-### One-time Completion
+### Use in Current Session
 
 For a single session without modifying your shell configuration:
 
@@ -101,29 +107,3 @@ source <(b completion bash)
 # Fish
 b completion fish | source
 ```
-
-## Completion Features
-
-- **Command Completion**: Tab-complete all available commands
-- **Flag Completion**: Complete flags for each command
-- **Argument Completion**: Context-aware completion for arguments
-- **Flag Value Completion**: Smart completion for flag values
-- **Descriptions**: Show help text for completions (in supported shells)
-
-## Shell-Specific Notes
-
-### Bash
-
-For better completion experience with bash, consider installing the `bash-completion` package:
-
-```bash
-# On macOS with Homebrew
-brew install bash-completion
-
-# On Ubuntu/Debian
-sudo apt-get install bash-completion
-```
-
-### Zsh
-
-If you're using Oh My Zsh, the completion should work out of the box after installation.
diff --git a/www/apps/docs/content/b/subcommands/init.mdx b/www/apps/docs/content/b/subcommands/init.mdx
index d571c3d..9ba866a 100644
--- a/www/apps/docs/content/b/subcommands/init.mdx
+++ b/www/apps/docs/content/b/subcommands/init.mdx
@@ -1,89 +1,48 @@
 ---
-description: "Initialize a new project with b"
+description: "Create new b.yaml config"
 ---
 
 # b init
 
-The `b init` command initializes a new project with **b** configuration, creating the necessary **b.yaml** file and setting up the project structure.
+Creates a new `.bin/b.yaml` configuration file in the current directory. Environment variables have precedence over the configuration file.
 
-## Synopsis
+## Usage
 
 ```bash
-b init [options]
+b init [flags]
 ```
 
-## Description
-
-The `init` command creates a new **b.yaml** configuration file in the current directory and optionally sets up additional project files like `.gitignore` and shell integration scripts.
-
-## Options
-
-- `--quiet, -q`: Run in quiet mode with minimal output
-- `--help, -h`: Show help information
-
 ## Examples
 
-### Basic Initialization
+### Create default config
+
+This command creates a new `b.yaml` in the `.bin` directory of your current location.
 
 ```bash
-# Initialize b in current directory
+# Create new b.yaml in current directory
 b init
 ```
 
-This creates a basic **b.yaml** file:
+### Create with custom path
 
-```yaml
-version: v1
-binaries:
-  b: {}
-```
-
-### Project Structure
-
-After initialization, your project will have:
+You can specify a custom path for the configuration file using the `--config` global flag.
 
+```bash
+# Create with custom path
+b init --config ./custom/b.yaml
 ```
-project/
-├── .bin
-│   ├── .gitignore
-│   └── b.yaml
-└── .envrc
-```
-
-## Configuration File
-
-The generated **b.yaml** file serves as the central configuration for your project's binary dependencies:
-
-```yaml
-binaries:
-  # Binary dependencies will be added here
-  # Example:
-  # jq:
-  #   version: "1.6"
-  # kubectl:
-  #   version: "1.28.0"
-```
-
-## Best Practices
 
-1. **Version Control**: Always commit the **b.yaml** file to version control
-2. **Team Collaboration**: Initialize **b** in shared project repositories
-3. **CI/CD**: Use `b init` in CI/CD pipelines before installing dependencies
-4. **Documentation**: Document your binary requirements in the project README
-
-## Integration with Git
-
-The `init` command automatically creates or updates `.gitignore` to exclude:
-
-```gitignore
-# b
-.bin/
-```
+## Flags
 
-## Error Handling
+| Flag         | Description              |
+|--------------|--------------------------|
+| `-h`, `--help` | help for init            |
 
-Common issues and solutions:
+## Global Flags
 
-- **Permission denied**: Ensure write permissions in the current directory
-- **File exists**: The command will not overwrite existing **b.yaml** files
-- **Invalid directory**: Run from a valid project directory
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
diff --git a/www/apps/docs/content/b/subcommands/install.mdx b/www/apps/docs/content/b/subcommands/install.mdx
index d594bc8..37404fa 100644
--- a/www/apps/docs/content/b/subcommands/install.mdx
+++ b/www/apps/docs/content/b/subcommands/install.mdx
@@ -1,85 +1,72 @@
 ---
-description: "Install and manage binaries with b CLI"
+description: "Install binaries from b.yaml or ad-hoc"
 ---
 
 # b install
 
-The `b install` command downloads and installs binaries, managing their versions and updating your project configuration.
+Install binaries. If no arguments are given, `b` installs all binaries from the `b.yaml` configuration file. You can also install specific binaries on-the-fly.
 
-## Synopsis
+## Usage
 
 ```bash
-b install [options] [binary[@version]...]
+b install [binary...] [flags]
 ```
 
-## Description
+## Examples
 
-The `install` command downloads binaries from GitHub releases and makes them available in your project. It can install specific versions, update existing installations, and automatically manage your `b.yaml` configuration.
+### Install all binaries from config
 
-## Options
+If a `b.yaml` file is present, this command will install all the binaries listed in it.
 
-- `--add, -a`: Add installed binaries to b.yaml configuration
-- `--force, -f`: Force reinstallation even if already installed
-- `--quiet, -q`: Run in quiet mode with minimal output
-- `--help, -h`: Show help information
+```bash
+b install
+```
 
-## Examples
+### Install a specific binary
 
-### Install Specific Binaries
+Install the latest version of a specific binary.
 
 ```bash
-# Install latest version
 b install jq
-
-# Install specific version
-b install jq@1.6
-
-# Install multiple binaries
-b install jq kubectl terraform
 ```
 
-### Install and Add to Configuration
+### Install a specific version
 
-```bash
-# Install and add to b.yaml
-b install --add jq@1.6
+Append `@<version>` to the binary name to install a specific version.
 
-# Install multiple with specific versions
-b install --add jq@1.6 kubectl@1.28.0
+```bash
+b install jq@jq-1.7
 ```
 
-### Install from Configuration
+### Install and add to config
 
-```bash
-# Install all binaries from b.yaml
-b install
+Use the `--add` flag to install a binary and simultaneously add it to your `b.yaml`.
 
-# Force reinstall all
-b install --force
+```bash
+b install --add kubectl
 ```
 
-## Version Resolution
+### Force an installation
 
-The install command supports flexible version specifications:
+Use the `--force` flag to overwrite an existing binary.
 
-- `latest`: Always installs the most recent version
-- `1.6`: Installs exactly version 1.6
-- `1.6.0`: Installs exactly version 1.6.0
-
-## Installation Process
+```bash
+b install --force jq
+```
 
-1. **Version Resolution**: Determines the exact version to install
-2. **Download**: Fetches the binary from GitHub releases
-3. **Verification**: Validates the downloaded binary
-4. **Installation**: Places the binary in the managed directory
-5. **PATH Management**: Ensures the binary is available in PATH
-6. **Configuration Update**: Updates b.yaml if `--add` is specified
+## Flags
 
-## Error Handling
+| Flag         | Description                               |
+|--------------|-------------------------------------------|
+| `--add`      | Add binary to b.yaml during install       |
+| `--fix`      | Pin the specified version in b.yaml       |
+| `-h`, `--help` | help for install                          |
 
-Common issues and solutions:
+## Global Flags
 
-- **Version not found**: Check available versions with `b search <binary>`
-- **Download failed**: Verify internet connection and GitHub access
-- **Permission denied**: Ensure write permissions to installation directory
-- **Binary not executable**: The install command automatically sets execute permissions
\ No newline at end of file
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
\ No newline at end of file
diff --git a/www/apps/docs/content/b/subcommands/list.mdx b/www/apps/docs/content/b/subcommands/list.mdx
index 148122f..a14f5cc 100644
--- a/www/apps/docs/content/b/subcommands/list.mdx
+++ b/www/apps/docs/content/b/subcommands/list.mdx
@@ -1,73 +1,63 @@
 ---
-description: "List installed binaries and their versions"
+description: "List project binaries and their installation status"
 ---
 
 # b list
 
-The `b list` command displays all installed binaries and their current versions.
+Lists all binaries defined in the project's `b.yaml` and their installation status.
 
-## Synopsis
+## Aliases
 
-```bash
-b list [options] [binary...]
-```
-
-## Description
-
-The `list` command shows information about installed binaries, including their versions, installation paths, and configuration status.
+- `ls`
+- `l`
 
-## Options
+## Usage
 
-- `--quiet, -q`: Show only binary names and versions
-- `--help, -h`: Show help information
+```bash
+b list [flags]
+```
 
 ## Examples
 
-### List All Binaries
+### List all binaries
+
+This command lists all binaries from the `b.yaml` file and shows whether they are installed.
 
 ```bash
-# List all installed binaries
+# List all binaries from b.yaml
 b list
 ```
 
-Output:
-```
-jq          1.6      ~/.local/share/b/bin/jq
-kubectl     1.28.0   ~/.local/share/b/bin/kubectl
-terraform   1.5.7    ~/.local/share/b/bin/terraform
-```
+### List as JSON
 
-### List Specific Binaries
+Use the `--output` global flag to format the list as JSON.
 
 ```bash
-# List specific binaries
-b list jq kubectl
+# List as JSON
+b list --output json
 ```
 
-### Quiet Mode
+### List as YAML
 
-```bash
-# Show only names and versions
-b list --quiet
-```
+Use the `--output` global flag to format the list as YAML.
 
-Output:
-```
-jq 1.6
-kubectl 1.28.0
-terraform 1.5.7
+```bash
+# List as YAML
+b list --output yaml
 ```
 
-## Output Format
+## Flags
 
-The default output includes:
-- **Binary Name**: The name of the installed binary
-- **Version**: The currently installed version
-- **Path**: The full path to the binary
+| Flag         | Description              |
+|--------------|--------------------------|
+| `-h`, `--help` | help for list            |
 
-## Configuration Status
+## Global Flags
 
-The list command shows which binaries are:
-- ✅ **Configured**: Listed in b.yaml
-- ⚠️ **Installed but not configured**: Installed but not in b.yaml
-- ❌ **Configured but not installed**: Listed in b.yaml but not installed
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-o`, `--output stringArray` | output options: json|yaml|format                                     |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
diff --git a/www/apps/docs/content/b/subcommands/request.mdx b/www/apps/docs/content/b/subcommands/request.mdx
index dcf2e08..25d1db7 100644
--- a/www/apps/docs/content/b/subcommands/request.mdx
+++ b/www/apps/docs/content/b/subcommands/request.mdx
@@ -1,52 +1,46 @@
 ---
-description: "Request new binaries to be added to b CLI"
+description: "Request a binary by creating a GitHub issue with a prefilled template"
 ---
 
 # b request
 
-The `b request` command helps users request new binaries to be added to the b CLI ecosystem by creating GitHub issues with the appropriate template.
+Request a binary by creating a GitHub issue with a prefilled template. This command streamlines the process of requesting new binaries to be added to `b`.
 
-## Synopsis
+## Usage
 
 ```bash
-b request [options] <binary-name>
+b request <binary-name> [flags]
 ```
 
-## Description
-
-The `request` command streamlines the process of requesting new binaries to be added to the b CLI. It opens your default web browser to create a new GitHub issue with a pre-filled template, making it easy to request new tools.
-
-## Options
-
-- `--help, -h`: Show help information
-
 ## Examples
 
-### Basic Usage
+### Request a new binary
 
 ```bash
-# Request a new binary to be added
-b request my-cool-tool
+# Request a new binary
+b request terraform
 ```
 
-## Request Process
+### Request with a description
 
-When you submit a request:
+If the binary name contains spaces or special characters, wrap it in quotes.
+
+```bash
+# Request with description
+b request "my-custom-tool"
+```
 
-1. The command collects information about your system
-2. Opens a new issue in the b CLI GitHub repository
-3. Pre-fills a template with:
-   - Requested binary name
-   - Your system information
-   - Any additional notes you provided
-   - Version of b CLI you're using
+## Flags
 
-## Request Guidelines
+| Flag         | Description               |
+|--------------|---------------------------|
+| `-h`, `--help` | help for request          |
 
-For the best chance of your request being accepted:
+## Global Flags
 
-1. **Check existing issues** first to avoid duplicates
-2. **Provide a clear use case** for the binary
-3. **Include relevant links** to the project's homepage
-4. **Mention any alternatives** you've considered
-5. **Be specific** about versions or features needed
\ No newline at end of file
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
\ No newline at end of file
diff --git a/www/apps/docs/content/b/subcommands/search.mdx b/www/apps/docs/content/b/subcommands/search.mdx
index 19d640d..5adbd24 100644
--- a/www/apps/docs/content/b/subcommands/search.mdx
+++ b/www/apps/docs/content/b/subcommands/search.mdx
@@ -1,44 +1,59 @@
 ---
-description: "Search for available binaries in the b CLI ecosystem"
+description: "Search available binaries"
 ---
 
 # b search
 
-The `b search` command helps you discover binaries available in the b CLI ecosystem, showing detailed information about each package including versions, descriptions, and installation commands.
+Discovers all binaries available for installation. The search can be filtered with a query.
 
-## Synopsis
+## Alias
+
+- `s`
+
+## Usage
 
 ```bash
-b search [options] [query]
+b search [query] [flags]
 ```
 
-## Description
+## Examples
 
-The `search` command queries the b CLI package registry to find binaries matching your search criteria. It's the best way to discover new tools and check available versions before installation.
+### List all available binaries
 
-## Options
+Run the command without a query to see all available binaries.
 
-- `--output, -o`: Output format (json, yaml, table)
-- `--help, -h`: Show help information
+```bash
+b search
+```
 
-## Examples
+### Search for specific binaries
 
-### Basic Search
+Provide a query to filter the results.
 
 ```bash
-# Search for a specific binary
 b search jq
-
-# Search with partial match
-b search py
 ```
 
-### Advanced Search
+### Search with JSON output
 
-```bash
-# Show all available packages
-b search
+Use the `--output` global flag to get the results in JSON format.
 
-# Get results in JSON format
-b search --output json jq
+```bash
+b search --output json
 ```
+
+## Flags
+
+| Flag         | Description               |
+|--------------|---------------------------|
+| `-h`, `--help` | help for search           |
+
+## Global Flags
+
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-o`, `--output stringArray` | output options: json|yaml|format                                     |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
diff --git a/www/apps/docs/content/b/subcommands/update.mdx b/www/apps/docs/content/b/subcommands/update.mdx
index 8f4fcdc..e5ee2c4 100644
--- a/www/apps/docs/content/b/subcommands/update.mdx
+++ b/www/apps/docs/content/b/subcommands/update.mdx
@@ -1,84 +1,58 @@
 ---
-description: "Update installed binaries to their latest versions"
+description: "Update binaries to their latest versions"
 ---
 
 # b update
 
-The `b update` command checks for and installs newer versions of previously installed binaries, ensuring your tools stay up-to-date.
+Update binaries. If no arguments are given, `b` updates all binaries from the `b.yaml` configuration file.
 
-## Synopsis
+## Alias
 
-```bash
-b update [options] [binary...]
-```
-
-## Description
-
-The `update` command checks GitHub releases for newer versions of your installed binaries and updates them if available. It respects version constraints in your `b.yaml` configuration while updating to the latest compatible version.
-
-## Options
-
-- `--all, -a`: Update all installed binaries
-- `--force, -f`: Force update even if already at latest version
-- `--quiet, -q`: Run in quiet mode with minimal output
-- `--check, -c`: Check for updates without installing
-- `--help, -h`: Show help information
-
-## Examples
+- `u`
 
-### Check for Updates
+## Usage
 
 ```bash
-# Check for updates without installing
-b update --check
-
-# Check specific binaries
-b update --check jq kubectl
+b update [binary...] [flags]
 ```
 
-### Update Binaries
+## Examples
 
-```bash
-# Update all installed binaries
-b update --all
+### Update all binaries
 
-# Update specific binaries
-b update jq kubectl
+If a `b.yaml` file is present, this command will update all the binaries listed in it to their latest available versions.
 
-# Force update even if at latest version
-b update --force jq
+```bash
+b update
 ```
 
-### Update Configuration
+### Update a specific binary
+
+Update a single binary to its latest version.
 
 ```bash
-# Update binaries and save versions to b.yaml
-b update --all --save
+b update jq
 ```
 
-## Version Constraints
-
-When updating, the command respects version constraints in your `b.yaml`:
+### Force an update
 
-- `^1.2.3`: Updates to the latest 1.x.x version
-- `~1.2.3`: Updates to the latest 1.2.x version
-- `>1.2.3`: Updates to any version above 1.2.3
-- `1.2.3`: Keeps exactly this version (use --force to override)
+Force an update even if the binary is already at the latest version. This is useful for re-installing a corrupted binary.
 
-## Update Process
+```bash
+b update --force kubectl
+```
 
-1. **Version Check**: Compares installed versions with latest available
-2. **Dependency Resolution**: Ensures compatibility between dependencies
-3. **Download**: Fetches updated binaries from GitHub releases
-4. **Verification**: Validates the downloaded binaries
-5. **Backup**: Creates backups of existing binaries before updating
-6. **Update**: Replaces old binaries with new versions
+## Flags
 
-## Error Handling
+| Flag         | Description               |
+|--------------|---------------------------|
+| `-h`, `--help` | help for update           |
 
-Common issues and solutions:
+## Global Flags
 
-- **Update failed**: Check network connection and GitHub access
-- **Version conflict**: Review version constraints in b.yaml
-- **Permission denied**: Ensure write permissions to installation directory
-- **Binary in use**: Close applications using the binary before updating
\ No newline at end of file
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
\ No newline at end of file
diff --git a/www/apps/docs/content/b/subcommands/version.mdx b/www/apps/docs/content/b/subcommands/version.mdx
index 71d994b..75bd42d 100644
--- a/www/apps/docs/content/b/subcommands/version.mdx
+++ b/www/apps/docs/content/b/subcommands/version.mdx
@@ -1,113 +1,78 @@
 ---
-description: "Display version information for b CLI and installed binaries"
+description: "Show version information for b and installed binaries"
 ---
 
 # b version
 
-The `b version` command displays version information about the b CLI tool and its installed binaries, helping you track which versions are currently in use.
+List all versions. If arguments are given, it shows the version of the specified binaries.
 
-## Synopsis
+## Alias
 
-```bash
-b version [options] [binary...]
-```
-
-## Description
+- `v`
 
-The `version` command shows detailed version information about the b CLI itself and any installed binaries. It's useful for debugging, reporting issues, and ensuring compatibility between different components.
+## Usage
 
-## Options
-
-- `--short, -s`: Show only version numbers
-- `--json`: Output in JSON format
-- `--all, -a`: Show versions of all installed binaries
-- `--help, -h`: Show help information
+```bash
+b version [binary...] [flags]
+```
 
 ## Examples
 
-### Basic Usage
+### Show all versions
+
+Run without arguments to see the version of `b` and all binaries in your `b.yaml`.
 
 ```bash
-# Show b CLI version
 b version
-
-# Show version in short format
-b version --short
 ```
 
-### Check Binary Versions
-
-```bash
-# Check version of specific binaries
-b version jq kubectl
+### Show specific binary version
 
-# Show versions of all installed binaries
-b version --all
+Pass a binary name to see its version.
 
-# Get version information in JSON format
-b version --json
+```bash
+b version jq
 ```
 
-## Version Information
-
-The version command displays several types of version information:
+### Show multiple binary versions
 
-1. **CLI Version**: The version of the b CLI tool
-2. **Runtime Information**: Go version and build platform
-3. **Binary Versions**: For each specified binary:
-   - Installed version
-   - Latest available version
-   - Whether an update is available
-   - Source of installation
-   - Last checked/updated timestamp
+```bash
+b version jq kubectl helm
+```
 
-## Output Formats
+### Show only local versions
 
-### Standard Output
-```
-b version 1.2.3 (go1.19.5 darwin/amd64)
+The `--local` flag prevents `b` from checking for new remote versions.
 
-jq: jq-1.6 (latest: jq-1.7) [Update available]
-kubectl: v1.28.0 (latest: v1.28.0) [Up to date]
+```bash
+b version --local
 ```
 
-### JSON Output (--json)
-```json
-{
-  "cli": {
-    "version": "1.2.3",
-    "goVersion": "go1.19.5",
-    "platform": "darwin/amd64"
-  },
-  "binaries": {
-    "jq": {
-      "installed": "jq-1.6",
-      "latest": "jq-1.7",
-      "updateAvailable": true,
-      "source": "github.com/stedolan/jq"
-    }
-  }
-}
-```
+### Check if versions are up to date
 
-## Integration with CI/CD
+The `--check` flag can be used in scripts to verify if binaries are up to date. It will exit with a non-zero status code if any binary is outdated.
 
-The `--short` and `--json` flags are particularly useful in CI/CD pipelines:
+```bash
+# Check if all versions are up to date (exit code based)
+b version --quiet --check
 
-```yaml
-# Example GitHub Actions workflow step
-- name: Verify binary versions
-  run: |
-    if [ "$(b version --short jq)" != "1.6" ]; then
-      echo "Incorrect jq version"
-      exit 1
-    fi
+# Check specific binaries
+b version jq kubectl --check
 ```
 
-## Error Handling
+## Flags
+
+| Flag         | Description                                         |
+|--------------|-----------------------------------------------------|
+| `--check`    | Check if versions are up to date (exit code based)  |
+| `-h`, `--help`   | help for version                                    |
+| `--local`    | Only show local versions, no lookup for new versions|
 
-Common issues and solutions:
+## Global Flags
 
-- **Binary not found**: The specified binary is not installed
-- **Version check failed**: Could not determine latest version (check network connection)
-- **Permission denied**: Insufficient permissions to read version information
\ No newline at end of file
+| Flag                 | Description                                                              |
+|----------------------|--------------------------------------------------------------------------|
+| `-c`, `--config string`  | Path to configuration file (current: `/home/fentas/github/fentas/b/.bin/b.yaml`) |
+| `--force`            | Force operations, overwriting existing binaries                          |
+| `-q`, `--quiet`      | Quiet mode                                                               |
+| `-v`, `--version`    | Print version information and quit                                       |
\ No newline at end of file
diff --git a/www/apps/docs/content/contribution/b.md b/www/apps/docs/content/contribution/b.md
index aa644e9..12a9280 100644
--- a/www/apps/docs/content/contribution/b.md
+++ b/www/apps/docs/content/contribution/b.md
@@ -13,12 +13,12 @@ b is a binary manager for developers that simplifies installation, versioning, a
 
 ### Binaries
 
-Binaries are the actual command-line tools that are managed by b. They are stored in the `binaries` directory in the b repository and registered in `cmd/b/main.go`.
+Binaries are the command-line tools managed by b. Their definitions are stored as individual Go files in the `pkg/binaries` directory. Adding a new file to this directory is sufficient to register a new binary; no manual registration in `cmd/b/main.go` is needed.
 
 ```
 ├── cmd
 │   └── b
-│       └── # All supported binaries are added here
+│       └── # Root command where subcommands are registered
 ├── pkg
 │   ├── binaries
 │   │   └── # Binary definitions
diff --git a/www/apps/docs/content/contribution/docs.md b/www/apps/docs/content/contribution/docs.md
index 1121d38..6a1b365 100644
--- a/www/apps/docs/content/contribution/docs.md
+++ b/www/apps/docs/content/contribution/docs.md
@@ -9,7 +9,7 @@ Thank you for your interest in contributing to the documentation! You will be he
 
 :::tip
 
-This guide is specific to contributing to the documentation. If you’re interested in contributing to b’s codebase, check out the [contributing guidelines in the Medusa GitHub repository](https://github.com/fentas/b/blob/develop/CONTRIBUTING.md).
+This guide is specific to contributing to the documentation. If you’re interested in contributing to b’s codebase, check out the [contributing guidelines in the b GitHub repository](https://github.com/fentas/b/blob/main/CONTRIBUTING.md).
 
 :::
 
@@ -310,19 +310,19 @@ import TabItem from '@theme/TabItem';
 
 
 <Tabs groupId="request-type" isCodeTabs={true}>
-  <TabItem value="globally" label="Install global" default>
+  <TabItem value="install" label="Install Binary" default>
 
     ```bash
-    curl -sL https://get.arg.sh | sudo tee /usr/local/bin/argsh > /dev/null
-    sudo chmod +x /usr/local/bin/argsh
+    # Install the latest version of a binary
+    b install jq
     ```
 
   </TabItem>
-  <TabItem value="locally" label="Withing a project">
+  <TabItem value="add" label="Add to Config">
 
     ```bash
-    curl -sL https://get.arg.sh > .bin/argsh
-    chmod +x .bin/argsh
+    # Install a binary and add it to your b.yaml
+    b install --add jq
     ```
 
   </TabItem>
@@ -360,7 +360,7 @@ For example:
 
 ~~~md
 ```bash noReport
-b install argsh
+b install jq
 ```
 ~~~
 
@@ -381,7 +381,7 @@ source ~/.bashrc
 
 ## Linting with Vale
 
-Argsh uses [Vale](https://vale.sh/) to lint documentation pages and perform checks on incoming PRs into the repository.
+b uses [Vale](https://vale.sh/) to lint documentation pages and perform checks on incoming PRs into the repository.
 
 ### Result of Vale PR Checks
 
@@ -391,12 +391,12 @@ You can check the result of running the "lint" action on your PR by clicking the
 
 If you want to check your work locally, you can do that by:
 
-1. [Installing direnv](https://direnv.net/) and running `direnv allow` in the root directory of the argsh repository.
+1. [Installing direnv](https://direnv.net/) and running `direnv allow` in the root directory of the b repository.
 2. Linting with `vale`:
 
 ```bash
 # to lint content for the main documentation
-argsh lint --vale error
+vale www/apps/docs/content
 ```
 
 ### VS Code Extension
@@ -420,7 +420,7 @@ You can also disable specific rules. For example:
 ```md
 <!-- vale docs.Numbers = NO -->
 
-Argsh supports Bash version 4.3 and later.
+b supports Bash version 4.3 and later.
 
 <!-- vale docs.Numbers = YES -->
 ```
@@ -431,24 +431,16 @@ If you use this in your PR, you must justify its usage.
 
 ## Linting with ESLint
 
-Argsh uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
+b uses ESlint to lint code blocks both in the content and the code base of the documentation apps.
 
 ### Linting Code/Content with ESLint
 
 Each PR runs through a check that lints the code in the content files using ESLint. The action's name is `code-docs-eslint`.
 
-If you want to check code ESLint errors locally and fix them, you can do that by:
-
-1\. Set up [direnv](https://direnv.net/) then run in the `root` directory:
-
-```bash
-direnv allow
-```
-
-2\. Then execute the following command anywhere:
+If you want to check code ESLint errors locally and fix them, you can do that by running the following command from the `www` directory:
 
 ```bash
-gofmt -s -w .
+yarn lint:fix
 ```
 
 This will fix any fixable errors, and show errors that require your action.
diff --git a/www/apps/docs/content/getting-started.mdx b/www/apps/docs/content/getting-started.mdx
index 5bc9122..8a0dae1 100644
--- a/www/apps/docs/content/getting-started.mdx
+++ b/www/apps/docs/content/getting-started.mdx
@@ -48,7 +48,7 @@ This creates a `b.yaml` file in your project root.
 
 ```bash
 # Install specific versions
-b install jq@jq-1.6 kubectl@v1.28.0
+b install jq@jq-1.7 kubectl@v1.28.0
 
 # Install latest versions
 b install terraform helm
@@ -62,8 +62,8 @@ b install --add docker-compose@v2.20.0
 Tools are automatically available in your PATH:
 
 ```bash
-jq --version     # 1.6
-kubectl version  # 1.28.0
+jq --version     # jq-1.7
+kubectl version  # v1.28.0
 ```
 
 ## Common Workflows
@@ -74,10 +74,10 @@ Share tool requirements with your team:
 
 ```bash
 # Add tools to b.yaml
-b install --add jq@jq-1.6 kubectl@v1.28.0
+b install --add jq@jq-1.7 kubectl@v1.28.0
 
 # Commit b.yaml to version control
-git add b.yaml
+git add .bin/b.yaml
 git commit -m "Add project tool requirements"
 
 # Team members can install the same tools
@@ -93,6 +93,7 @@ Use **b** in your CI/CD pipelines:
 steps:
   - uses: actions/checkout@v4
   - name: Install b
+    # todo: wrong url; create install script
     run: curl -sSL https://github.com/fentas/b/releases/latest/download/install.sh | bash
   - name: Install project tools
     run: b install
@@ -105,31 +106,31 @@ steps:
 ### Version Management
 
 ```bash
-# List installed tools
+# List configured tools and their status
 b list
 
-# Update tools to latest versions
+# Update all tools to latest versions
 b update
 
 # Update specific tools
-b update kubectl terraform
+b update kubectl
 
 # Search for available tools
-b search docker
+b search terraform
 ```
 
 ## Configuration
 
-The `b.yaml` file defines your project's tool requirements:
+The `.bin/b.yaml` file defines your project's tool requirements:
 
 ```yaml
 binaries:
   jq:
-    version: "jq-1.6"
+    version: "jq-1.7"
   kubectl:
     version: "v1.28.0"
+  # leave empty for latest version
   terraform:
-    version: "latest"
 ```
 
 ## Next Steps
diff --git a/www/apps/docs/content/glossary.mdx b/www/apps/docs/content/glossary.mdx
index 548f136..e7e2b34 100644
--- a/www/apps/docs/content/glossary.mdx
+++ b/www/apps/docs/content/glossary.mdx
@@ -10,7 +10,7 @@ This glossary defines key terms and concepts used throughout the **b** documenta
 
 **b** - A modern binary manager for developers that simplifies installation, versioning, and management of command-line tools.
 
-**b.yaml** - The configuration file that defines binary dependencies for a project. Contains version specifications and metadata.
+**.bin/b.yaml** - The configuration file that defines binary dependencies for a project, typically located in the `.bin` directory. Contains version specifications and metadata.
 
 **Binary** - An executable command-line tool managed by **b** (e.g., `jq`, `kubectl`, `terraform`).
 
@@ -20,7 +20,7 @@ This glossary defines key terms and concepts used throughout the **b** documenta
 
 **CLI** - Command Line Interface. The text-based interface used to interact with **b**.
 
-**Configuration Discovery** - The process by which **b** automatically locates and loads the nearest `b.yaml` file in the directory hierarchy.
+**Configuration Discovery** - The process by which **b** automatically locates and loads the nearest `.bin/b.yaml` file in the directory hierarchy.
 
 **Context-Aware** - **b**'s ability to automatically detect and use project-specific configurations without explicit file paths.
 
@@ -54,7 +54,7 @@ This glossary defines key terms and concepts used throughout the **b** documenta
 
 **PATH Management** - **b**'s automatic handling of adding managed binaries to the system PATH.
 
-**Project-Based Configuration** - Using **b.yaml** files to define tool requirements specific to individual projects.
+**Project-Based Configuration** - Using `.bin/b.yaml` files to define tool requirements specific to individual projects.
 
 ## S
 
diff --git a/www/apps/docs/content/homepage.mdx b/www/apps/docs/content/homepage.mdx
index c89f351..1d2b963 100644
--- a/www/apps/docs/content/homepage.mdx
+++ b/www/apps/docs/content/homepage.mdx
@@ -1,6 +1,6 @@
 ---
 id: homepage
-title: b Documentation
+title: b documentation
 description: "b is a binary manager for developers - install, manage, and version your command-line tools effortlessly."
 slug: /
 hide_table_of_contents: true
@@ -63,11 +63,11 @@ Managing command-line tools across different projects and environments is challe
 b init
 
 # Install tools for your project
-b install jq@1.6 kubectl@1.28.0
+b install jq@jq-1.7 kubectl@v1.28.0
 
 # Tools are now available
-jq --version  # 1.6
-kubectl version --client  # 1.28.0
+jq --version              # jq-1.7
+kubectl version --client  # v1.28.0
 ```
 
 ## Explore b
diff --git a/www/apps/docs/content/troubleshooting.mdx b/www/apps/docs/content/troubleshooting.mdx
index 79acd1f..0c4d082 100644
--- a/www/apps/docs/content/troubleshooting.mdx
+++ b/www/apps/docs/content/troubleshooting.mdx
@@ -39,9 +39,9 @@ source ~/.zshrc
 
 ## Configuration Issues
 
-### b.yaml Not Found
+### .bin/b.yaml Not Found
 
-**Problem**: `b.yaml configuration file not found`
+**Problem**: `configuration file not found`
 
 **Solution**:
 ```bash
@@ -49,28 +49,29 @@ source ~/.zshrc
 cd your-project
 b init
 
-# Or create b.yaml manually
-cat > b.yaml << EOF
+# Or create .bin/b.yaml manually
+mkdir -p .bin
+cat > .bin/b.yaml << EOF
 binaries: {}
 EOF
 ```
 
 ### Invalid Configuration
 
-**Problem**: YAML parsing errors in **b.yaml**
+**Problem**: YAML parsing errors in `.bin/b.yaml`
 
 **Solution**:
 ```bash
 # Validate your YAML syntax
 # Check for proper indentation and structure
-cat b.yaml
+cat .bin/b.yaml
 
 # Example valid format:
 binaries:
   jq:
-    version: "jq-1.6"
+    version: "1.7"
   kubectl:
-    version: "v1.28.0"
+    version: "1.28.0"
 ```
 
 ## Binary Installation Issues
@@ -84,11 +85,11 @@ binaries:
 # Check your internet connection
 curl -I https://github.com
 
-# Try with verbose output for debugging
-b install --verbose jq
-
 # Check GitHub API rate limits
 curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/rate_limit
+
+# If you are using a proxy, make sure your shell environment is configured correctly
+# (e.g., HTTP_PROXY, HTTPS_PROXY environment variables).
 ```
 
 ### Version Not Found
@@ -182,10 +183,8 @@ speedtest-cli
 # Check cache size
 du -sh ~/.local/share/b/
 
-# Clean up old versions (if implemented)
-b clean
-
-# Manually remove old binaries
+# Manually remove old binaries from the cache.
+# Note: A 'b clean' command is planned for a future release.
 rm -rf ~/.local/share/b/cache/
 ```
 
@@ -255,7 +254,7 @@ echo $SHELL
 echo $PATH
 
 # Configuration
-cat b.yaml
+cat .bin/b.yaml
 
 # Installed binaries
 b list