docs: update documentation with consistent paths, versions and formating

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.

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                                       |

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 [email protected]
-
-# 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 [email protected]
+Append `@<version>` to the binary name to install a specific version.
 
-# Install multiple with specific versions
-b install --add jq@1.6 [email protected]
+```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
+| 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                                       |