link-assistant · konard · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026
diff --git a/README.md b/README.md
@@ -81,7 +81,7 @@ We strongly recommend:
 - Never using production tokens or credentials
 - Being prepared to revoke and replace all tokens used with this system
 
-Minimum system requirements to run `hive.mjs`:
+**Minimum system requirements:**
 
 ```
 1 CPU Core
@@ -92,25 +92,20 @@ Minimum system requirements to run `hive.mjs`:
 
 ## 🚀 Quick Start
 
-### Global Installation
-
-#### Using Bun (Recommended)
-
-```bash
-bun install -g @link-assistant/hive-mind
-```
+Choose your preferred installation method:
 
-#### Using Node.js
-
-```bash
-npm install -g @link-assistant/hive-mind
-```
+| Method                  | Best For                              | Guide                                                   |
+| ----------------------- | ------------------------------------- | ------------------------------------------------------- |
+| **Docker**              | Local development, multiple instances | [Docker Installation](#docker-installation)             |
+| **Helm/Kubernetes**     | Production deployments, scaling       | [Helm Installation](#helm-installation)                 |
+| **Ubuntu 24.04 Server** | Dedicated VMs/VPS                     | [Server Installation](#ubuntu-2404-server-installation) |
+| **Global npm/bun**      | Quick local testing                   | [Global Installation](#global-installation)             |
 
 ### Docker Installation
 
 Run the Hive Mind using Docker for safer local installation - no manual setup required:
 
-**Note:** Docker is much safer for local installation and can be used to install multiple isolated instances on a server or Kubernetes cluster. For Kubernetes deployments, see the [Helm chart installation](#helm-installation-kubernetes) section below.
+**Note:** Docker is much safer for local installation and can be used to install multiple isolated instances on a server or Kubernetes cluster. For Kubernetes deployments, see the [Helm Installation](#helm-installation) section below.
 
 ```bash
 # Pull the latest image from Docker Hub
@@ -140,9 +135,9 @@ solve https://github.com/owner/repo/issues/123
 - ✅ Easy to run multiple instances with different GitHub accounts
 - ✅ Consistent environment across different machines
 
-See [docs/DOCKER.md](./docs/DOCKER.md) for advanced Docker usage.
+See [docs/DOCKER.md](./docs/DOCKER.md) for advanced Docker usage including persistent storage, Docker Compose, and CI/CD configuration.
 
-### Helm Installation (Kubernetes)
+### Helm Installation
 
 Deploy Hive Mind on Kubernetes using Helm:
 
@@ -170,7 +165,7 @@ See [docs/HELM.md](./docs/HELM.md) for detailed Helm configuration options.
 
 **Note:** The Helm chart is published to [ArtifactHub](https://artifacthub.io/packages/helm/link-assistant/hive-mind) for easy discovery.
 
-### Installation on Ubuntu 24.04 server
+### Ubuntu 24.04 Server Installation
 
 1. Reset/install VPS/VDS server with fresh Ubuntu 24.04
 2. Login to `root` user.
@@ -281,7 +276,23 @@ The oAuth callback server on 1455 port will be started, and the link to oAuth wi
 
 3. Use your browser on machine where you started the tunnel from, paste there the link from `codex login` command, and go there using your browser. Once redirected to localhost:1455 you will see successful login page, and in `codex login` you will see `Successfully logged in`. After that `codex login` command will complete, and you can use `codex` command as usual to verify. It should also be working with `--tool codex` in `solve` and `hive` commands.
 
-### Core Operations
+### Global Installation
+
+**For quick testing (not recommended for production).**
+
+#### Using Bun (Recommended)
+
+```bash
+bun install -g @link-assistant/hive-mind
+```
+
+#### Using Node.js
+
+```bash
+npm install -g @link-assistant/hive-mind
+```
+
+## Core Operations
 
 ```bash
 # Solve using maximum power
@@ -631,6 +642,18 @@ grep -E '\(cd /tmp/gh-issue-solver-[0-9]+ && claude --resume [0-9a-f-]{36}\)' hi
 
 For comprehensive configuration including environment variables, timeouts, retry limits, Telegram bot settings, YouTrack integration, and all CLI options, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
 
+## Documentation
+
+| Document                                           | Description                                         |
+| -------------------------------------------------- | --------------------------------------------------- |
+| [docs/USAGE.md](./docs/USAGE.md)                   | Complete CLI and Telegram bot usage guide           |
+| [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)   | All configuration options and environment variables |
+| [docs/FEATURES.md](./docs/FEATURES.md)             | Detailed feature explanations                       |
+| [docs/COMPARISON.md](./docs/COMPARISON.md)         | Comparisons with alternatives                       |
+| [docs/DOCKER.md](./docs/DOCKER.md)                 | Docker installation and configuration               |
+| [docs/HELM.md](./docs/HELM.md)                     | Kubernetes/Helm deployment guide                    |
+| [docs/BEST-PRACTICES.md](./docs/BEST-PRACTICES.md) | CI/CD recommendations for best results              |
+
 ## 🐛 Reporting Issues
 
 ### Hive Mind Issues
@@ -655,9 +678,9 @@ All documentation files are automatically checked:
 find docs/ -name "*.md" -exec wc -l {} + | awk '$1 > 1000 {print "ERROR: " $2 " has " $1 " lines (max 1000)"}'
 ```
 
-## Server diagnostics
+## Server Diagnostics
 
-Identify screens that are parents of processes that eating the resources
+Identify screens that are parents of processes eating the resources:
 
 ```bash
 TARGETS="62220 65988 63094 66606 1028071 4127023"
@@ -679,7 +702,7 @@ for p in $TARGETS; do
 done
 ```
 
-Show details about the proccess
+Show details about the process:
 
 ```bash
 procinfo() {
@@ -732,15 +755,15 @@ procinfo 62220
 
 ## Maintenance
 
-### Reboot server.
+### Reboot Server
 
 ```
 sudo reboot
 ```
 
-That will remove all dangling unused proccesses and screens, which will in turn free the RAM and reduce CPU load. Also reboot may clear all temporary files, so next step can do nothing if reboot was done.
+That will remove all dangling unused processes and screens, which will in turn free the RAM and reduce CPU load. Also reboot may clear all temporary files, so next step can do nothing if reboot was done.
 
-### Cleanup disk space.
+### Cleanup Disk Space
 
 ```
 df -h
@@ -758,7 +781,7 @@ sudo chown root:root /tmp
 sudo chmod 1777 /tmp
 ```
 
-### Close all screens to free up RAM
+### Close All Screens to Free up RAM
 
 ```bash
 # close all (Attached or Detached) sessions

diff --git a/docs/DOCKER.md b/docs/DOCKER.md
@@ -1,6 +1,6 @@
 # Docker Support for Hive Mind
 
-This document explains how to run Hive Mind in Docker containers.
+This document explains how to run Hive Mind in Docker containers. For usage instructions after installation, see [USAGE.md](./USAGE.md).
 
 ## Quick Start
 
@@ -105,7 +105,8 @@ This approach allows:
 ├── scripts/
 │   └── ubuntu-24-server-install.sh  # Installation script used by Dockerfile
 └── docs/
-    └── DOCKER.md                 # This file
+    ├── DOCKER.md                 # This file
+    └── USAGE.md                  # Usage instructions (CLI and Telegram bot)
 ```
 
 ## Advanced Usage
@@ -216,7 +217,7 @@ If you're maintaining a fork or want to publish to your own Docker Hub account,
 
 1. Log in to [hub.docker.com](https://hub.docker.com)
 2. Click on your username in the top-right corner
-3. Select **Account Settings** → **Security**
+3. Select **Account Settings** -> **Security**
 4. Click **New Access Token**
 5. Enter a description (e.g., "GitHub Actions - Hive Mind")
 6. Set permissions to **Read, Write, Delete** (required for publishing)
@@ -227,7 +228,7 @@ If you're maintaining a fork or want to publish to your own Docker Hub account,
 ### Step 3: Add Secrets to GitHub Repository
 
 1. Go to your GitHub repository (e.g., `https://github.com/konard/hive-mind`)
-2. Click **Settings** → **Secrets and variables** → **Actions**
+2. Click **Settings** -> **Secrets and variables** -> **Actions**
 3. Click **New repository secret**
 4. Add the following two secrets:
 
@@ -275,7 +276,7 @@ env:
 **Image published but can't pull:**
 
 - Ensure the repository on Docker Hub is public (or you're authenticated)
-- Check [hub.docker.com](https://hub.docker.com) → Your repositories → hive-mind → Settings → Make Public
+- Check [hub.docker.com](https://hub.docker.com) -> Your repositories -> hive-mind -> Settings -> Make Public
 
 **Build succeeds but image doesn't appear:**
 
@@ -291,3 +292,11 @@ env:
 - Authentication happens inside the container after it starts
 - Each GitHub/Claude account can have its own container instance
 - Docker Hub access tokens should be stored only as GitHub Secrets, never committed to the repository
+
+## Next Steps
+
+After installation and authentication, see [USAGE.md](./USAGE.md) for:
+
+- CLI commands (`solve`, `hive`)
+- Telegram bot setup
+- All available options
diff --git a/docs/HELM.md b/docs/HELM.md
@@ -1,6 +1,6 @@
-# Helm Chart Documentation
+# Helm Installation
 
-This document provides comprehensive guidance for deploying Hive Mind on Kubernetes using Helm.
+This document covers Kubernetes/Helm installation for Hive Mind. For usage instructions after installation, see [USAGE.md](./USAGE.md).
 
 ## Prerequisites
 
@@ -9,7 +9,7 @@ This document provides comprehensive guidance for deploying Hive Mind on Kuberne
 - `kubectl` configured to access your cluster
 - Sufficient cluster resources (see [Resource Requirements](#resource-requirements))
 
-## Installation
+## Quick Start
 
 ### Add the Helm Repository
 
@@ -41,10 +41,6 @@ helm install hive-mind link-assistant/hive-mind -n hive-mind
 
 ## Configuration
 
-### Default Values
-
-The default `values.yaml` provides sensible defaults for most deployments. Key configuration options:
-
 ### Resource Requirements
 
 Default resource allocation:
@@ -95,7 +91,7 @@ persistence:
 
 ### Authentication Configuration
 
-Hive Mind requires GitHub and Claude authentication. These should be configured via Kubernetes secrets:
+Hive Mind requires GitHub and Claude authentication. Configure via Kubernetes secrets:
 
 #### Create GitHub Token Secret
 
@@ -151,7 +147,7 @@ env:
 
 ### Autoscaling
 
-Enable horizontal pod autoscaling for multiple bot instances:
+Enable horizontal pod autoscaling:
 
 ```yaml
 autoscaling:
@@ -205,11 +201,11 @@ affinity:
           topologyKey: kubernetes.io/hostname
 ```
 
-## Common Use Cases
+## Deployment Examples
 
 ### Example 1: Single Bot Instance
 
-Simple deployment for testing or small-scale usage:
+Simple deployment for testing:
 
 ```yaml
 # values-simple.yaml
@@ -348,7 +344,7 @@ helm rollback hive-mind 2
 helm uninstall hive-mind
 ```
 
-**Note:** By default, PersistentVolumeClaims are not deleted automatically. To delete them:
+**Note:** PersistentVolumeClaims are not deleted automatically. To delete them:
 
 ```bash
 kubectl delete pvc -l app.kubernetes.io/name=hive-mind
@@ -466,7 +462,7 @@ volumeMounts:
     readOnly: true
 ```
 
-## Monitoring and Observability
+## Monitoring
 
 ### Resource Monitoring
 
@@ -478,7 +474,7 @@ kubectl top pods -l app.kubernetes.io/name=hive-mind
 watch kubectl top pods -l app.kubernetes.io/name=hive-mind
 ```
 
-### Logging
+### Logging Integration
 
 Integrate with logging systems like ELK, Loki, or CloudWatch:
 
@@ -526,13 +522,21 @@ podAnnotations:
 
 5. **Regular Updates:** Keep the chart and container image updated
 
-## Support and Contributing
+## Resources
 
 - **GitHub Issues:** https://github.com/link-assistant/hive-mind/issues
 - **Documentation:** https://github.com/link-assistant/hive-mind
 - **Docker Hub:** https://hub.docker.com/r/konard/hive-mind
 - **ArtifactHub:** https://artifacthub.io/packages/helm/link-assistant/hive-mind
 
+## Next Steps
+
+After installation and authentication, see [USAGE.md](./USAGE.md) for:
+
+- CLI commands (`solve`, `hive`)
+- Telegram bot setup
+- All available options
+
 ## License
 
 This Helm chart is released under the Unlicense. See the [LICENSE](https://github.com/link-assistant/hive-mind/blob/main/LICENSE) file for details.