docs: clarify container commands must run on host, add vault/vectordb examples

- Add warning that container create commands must run on HOST system
- Add runtime dependencies section with install script reference
- Add examples for creating vault and vectordb containers
- Update troubleshooting with dependency installation instructions

src/01-introduction/installation.md

@@ -2,6 +2,58 @@
 
 botserver installs itself automatically through the bootstrap process. Just run the binary.
 
+## Runtime Dependencies
+
+Before running the botserver binary, you must install required system libraries on the **host system**.
+
+### Quick Install (Recommended)
+
+Download and run the dependency installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash
+```
+
+Or if you have the script locally:
+
+```bash
+sudo ./scripts/install-dependencies.sh
+```
+
+### Manual Install (Debian/Ubuntu)
+
+```bash
+sudo apt update
+sudo apt install -y \
+    libpq5 \
+    libssl3 \
+    liblzma5 \
+    zlib1g \
+    ca-certificates \
+    curl \
+    wget
+
+# For container support (LXC)
+sudo snap install lxd
+sudo lxd init --auto
+```
+
+### Manual Install (Fedora/RHEL)
+
+```bash
+sudo dnf install -y \
+    libpq \
+    openssl-libs \
+    xz-libs \
+    zlib \
+    ca-certificates \
+    curl \
+    wget \
+    lxc
+```
+
+> ⚠️ **Common Error**: If you see `error while loading shared libraries: libpq.so.5`, install `libpq5` (Debian/Ubuntu) or `libpq` (Fedora/RHEL).
+
 ## System Requirements
 
 | Resource | Minimum | Production |
@@ -123,6 +175,19 @@ Requires CUDA installed and 12GB+ VRAM.
 | **Docker** | Production, microservices | [Docker Deployment](../chapter-07-gbapp/docker-deployment.md) |
 | **LXC** | Isolated components, Linux | [Container Deployment](../chapter-07-gbapp/containers.md) |
 
+> ⚠️ **IMPORTANT**: Container create commands (`botserver install ... --container`) must be run from the **host system**, not inside a container.
+
+### Example: Create Vault and VectorDB
+
+```bash
+# Run on HOST system
+botserver install vault --container --tenant mycompany
+botserver install vector_db --container --tenant mycompany
+
+# Verify containers
+lxc list | grep mycompany
+```
+
 ## Troubleshooting
 
 | Issue | Solution |

src/07-gbapp/containers.md

@@ -2,6 +2,8 @@
 
 botserver uses LXC (Linux Containers) for isolated component deployment with system-level containerization.
 
+> ⚠️ **IMPORTANT**: All container create and management commands must be run from the **host system**, not from inside a container. The botserver binary manages LXC containers from the host level.
+
 ## What is LXC?
 
 - **System containers** - Full Linux userspace (lightweight VMs)
@@ -11,6 +13,8 @@ botserver uses LXC (Linux Containers) for isolated component deployment with sys
 
 ## Automatic Setup
 
+Run on the **host system**:
+
 ```bash
 ./botserver --container
 ```
@@ -58,6 +62,8 @@ Data persists even if containers are deleted.
 
 ## Common Operations
 
+Run these commands on the **host system**:
+
 ```bash
 # List containers
 lxc list
@@ -114,10 +120,35 @@ lxc restore default-tables backup-2024-01-15
 | Easy cleanup/reinstall | Simple deployment |
 | Security isolation | Direct service access |
 
+## Example: Create Vault and VectorDB Containers
+
+Run on the **host system**:
+
+```bash
+# Install Vault for secrets management
+botserver install vault --container --tenant mycompany
+
+# Install VectorDB (Qdrant) for embeddings
+botserver install vector_db --container --tenant mycompany
+
+# Verify containers are running
+lxc list | grep mycompany
+
+# Get container IPs
+lxc list mycompany-vault -c n4 --format csv
+lxc list mycompany-vectordb -c n4 --format csv
+
+# Test services
+curl http://<vault-ip>:8200/v1/sys/health
+curl http://<vectordb-ip>:6333/health
+```
+
 ## Migration
 
 ### Local → Container
 
+Run on the **host system**:
+
 ```bash
 pg_dump botserver > backup.sql
 ./botserver --container
@@ -126,6 +157,8 @@ lxc exec default-tables -- psql -U gbuser botserver < backup.sql
 
 ### Container → Local
 
+Run on the **host system**:
+
 ```bash
 lxc exec default-tables -- pg_dump -U gbuser botserver > backup.sql
 ./botserver uninstall tables

src/19-maintenance/cli-reference.md

@@ -2,6 +2,8 @@
 
 botserver provides a command-line interface for managing components, secrets, and services.
 
+> ⚠️ **IMPORTANT**: All container create commands (`botserver install ... --container`) must be run from the **host system**, not from inside a container. The botserver binary manages LXC containers from the host level.
+
 ## General Usage
 
 ```bash
@@ -43,19 +45,52 @@ botserver <command> [options]
 botserver install <component> [--container] [--tenant <name>]
 ```
 
+> ⚠️ **Run from host**: Container install commands must be executed on the host machine, not inside any container.
+
 **Examples:**
 
 ```bash
 # Install vault locally
 botserver install vault
 
-# Install vault in an LXC container with tenant name
+# Install vault in an LXC container with tenant name (run on HOST)
 botserver install vault --container --tenant pragmatismo
 
-# Install vector database
+# Install vector database (run on HOST)
 botserver install vector_db --container --tenant pragmatismo
 ```
 
+**Example: Create Vault and VectorDB containers**
+
+This example shows how to create both Vault (secrets management) and VectorDB (Qdrant for embeddings) containers from scratch:
+
+```bash
+# Run these commands on the HOST system, not inside a container
+
+# Step 1: Install Vault container
+botserver install vault --container --tenant mycompany
+
+# Step 2: Install VectorDB (Qdrant) container
+botserver install vector_db --container --tenant mycompany
+
+# Step 3: Verify containers are running
+lxc list | grep mycompany
+
+# Expected output:
+# | mycompany-vault     | RUNNING | 10.x.x.x (eth0) | ... |
+# | mycompany-vectordb  | RUNNING | 10.x.x.x (eth0) | ... |
+
+# Step 4: Get container IPs for configuration
+lxc list mycompany-vault -c n4 --format csv
+lxc list mycompany-vectordb -c n4 --format csv
+
+# Step 5: Test Vault health
+curl http://<vault-ip>:8200/v1/sys/health
+
+# Step 6: Test VectorDB health
+curl http://<vectordb-ip>:6333/health
+```
+
 **Available Components:**
 
 | Component | Description |
@@ -463,13 +498,15 @@ botserver version --all
 
 ## Complete Setup Example
 
-Here's a complete workflow to set up Vault and migrate secrets:
+Here's a complete workflow to set up Vault and migrate secrets.
+
+> ⚠️ **Run all commands on the HOST system**, not inside any container.
 
 ```bash
-# 1. Install Vault in a container
+# 1. Install Vault in a container (run on HOST)
 botserver install vault --container --tenant pragmatismo
 
-# 2. Install Vector DB for embeddings
+# 2. Install Vector DB for embeddings (run on HOST)
 botserver install vector_db --container --tenant pragmatismo
 
 # 3. Get Vault container IP
@@ -632,8 +669,23 @@ lxc exec <tenant>-<component> -- journalctl -xe
 
 ### Missing Dependencies
 
+If you see errors like `error while loading shared libraries: libpq.so.5`, install the runtime dependencies:
+
 ```bash
-# Install system dependencies
+# Quick install (recommended) - run on HOST system
+curl -fsSL https://raw.githubusercontent.com/GeneralBots/botserver/main/scripts/install-dependencies.sh | sudo bash
+
+# Or manual install (Debian/Ubuntu)
+sudo apt-get install -y libpq5 libssl3 liblzma5 zlib1g ca-certificates curl wget
+
+# Or manual install (Fedora/RHEL)
+sudo dnf install -y libpq openssl-libs xz-libs zlib ca-certificates curl wget
+```
+
+For development/building from source:
+
+```bash
+# Install development dependencies
 sudo apt-get install -y libpq-dev libssl-dev liblzma-dev
 ```