diff --git a/README.md b/README.md
index 38e8840..c996313 100644
--- a/README.md
+++ b/README.md
@@ -497,33 +497,66 @@ MIT - Use it, modify it, share it.
 
 ## Docker
 
-### Pre-built Container (Fastest)
+### Pre-installed Container (Recommended)
 
-Pull and run the pre-built image directly:
+Ready-to-use container with CmdForge and 27 example tools pre-installed:
 
 ```bash
-# Pull from registry
-docker pull gitea.brrd.tech/rob/cmdforge:latest
+# Build from source
+docker build -f Dockerfile.ready -t cmdforge-ready .
 
-# Run CmdForge
-docker run -it --rm gitea.brrd.tech/rob/cmdforge cmdforge --help
+# Run interactively
+docker run -it --rm cmdforge-ready
 
-# List available tools
-docker run -it --rm gitea.brrd.tech/rob/cmdforge cmdforge list
-
-# Interactive shell
-docker run -it --rm gitea.brrd.tech/rob/cmdforge bash
+# With persistent storage (keeps your tools between runs)
+docker run -it --rm -v cmdforge-data:/home/user/.cmdforge cmdforge-ready
 ```
 
-### Build from Source
+Inside the container, CmdForge is ready to use:
+```bash
+cmdforge list            # See 27 pre-installed tools
+cmdforge ui              # Launch the TUI
+cmdforge run summarize   # Run a tool
+```
 
-Alternatively, build the container yourself:
+### Test Installation Container
+
+Simulates a fresh computer for testing the installation process:
 
 ```bash
-# Clone the repo
-git clone https://gitea.brrd.tech/rob/CmdForge.git
-cd CmdForge
+# Build the test container
+docker build -f Dockerfile.test-install -t cmdforge-test-install .
 
+# Run interactively
+docker run -it --rm cmdforge-test-install
+
+# Inside the container - run the installer
+cd ~/CmdForge
+./install.sh
+```
+
+### Interactive Installer
+
+The `install.sh` script provides guided installation:
+
+```bash
+./install.sh              # Full interactive install
+./install.sh --yes        # Non-interactive (accept defaults)
+./install.sh --no-venv    # Install without virtual environment
+./install.sh --no-examples # Skip installing example tools
+```
+
+Features:
+- Creates virtual environment at `~/.cmdforge-venv`
+- Configures PATH in your shell config (bash/zsh/fish)
+- Optionally installs 27 example tools
+- Works on macOS and Linux
+
+### Legacy Container
+
+The original docker-compose setup still works:
+
+```bash
 # Build the container
 docker-compose build