diff --git a/docs/docker/Dockerfile b/docs/docker/Dockerfile
new file mode 100644
index 0000000000..f6ef631260
--- /dev/null
+++ b/docs/docker/Dockerfile
@@ -0,0 +1,47 @@
+# Use Ubuntu with the appropriate architecture
+ARG ARCH=amd64
+FROM --platform=linux/${ARCH} ubuntu:latest
+
+# Set environment variables (timezone will be set at runtime)
+ENV DEBIAN_FRONTEND=noninteractive TERM="xterm-256color"
+
+# Install common dependencies and mise
+RUN apt-get update && apt-get install -y curl wget git jq vim nano unzip zip ssh ca-certificates \
+    gnupg lsb-release software-properties-common build-essential pkg-config tzdata sqlite3 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install AWS CLI and Amazon Q CLI with architecture detection
+ARG TARGETARCH
+RUN ARCH_AWS=$([ "$TARGETARCH" = "amd64" ] && echo "x86_64" || echo "aarch64") && \
+    curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-$ARCH_AWS.zip" -o awscliv2.zip && \
+    curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-$ARCH_AWS-linux.zip" -o q.zip && \
+    unzip awscliv2.zip && ./aws/install && rm -rf awscliv2.zip ./aws && \
+    unzip q.zip -d /tmp && chmod +x /tmp/q/install.sh && Q_INSTALL_GLOBAL=true /tmp/q/install.sh && \
+    rm -rf q.zip /tmp/q
+    
+# Create non-root user and set up directories
+RUN useradd -ms /bin/bash dev && \
+    mkdir -p /home/dev/src /home/dev/.aws/amazonq/profiles /home/dev/.ssh && \
+    mkdir -p /home/dev/.local/share/amazon-q /home/dev/.cache/amazon-q && \
+    chown -R dev:dev /home/dev
+
+# Switch to non-root user
+USER dev
+WORKDIR /home/dev/src
+
+RUN echo 'export PS1="\[\033[01;32m\]q-dev\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ "' >> /home/dev/.bashrc
+
+# Initialize the SQLite database to ensure proper permissions
+RUN mkdir -p /home/dev/.local/share/amazon-q && \
+    touch /home/dev/.local/share/amazon-q/data.sqlite3 && \
+    chmod 644 /home/dev/.local/share/amazon-q/data.sqlite3
+
+# Install mise for managing multiple language runtimes
+RUN curl https://mise.run | sh && \
+    echo 'eval "$(~/.local/bin/mise activate --shims bash)"' >> ~/.bashrc && \
+    eval "$(~/.local/bin/mise activate --shims bash)" && \
+    ~/.local/bin/mise use -g python@latest uv@latest node@lts java@latest go@latest
+
+# Default command starts Amazon Q chat
+ENTRYPOINT [ "q" ]
+CMD ["chat"]
diff --git a/docs/docker/customizing-docker-setup.md b/docs/docker/customizing-docker-setup.md
new file mode 100644
index 0000000000..d760418493
--- /dev/null
+++ b/docs/docker/customizing-docker-setup.md
@@ -0,0 +1,227 @@
+# Customizing the Docker Setup for Amazon Q CLI
+
+This guide provides detailed information for developers who want to customize or modify the Docker setup for Amazon Q CLI.
+
+## Dockerfile Details
+
+The default Dockerfile creates an Ubuntu-based container with:
+
+```dockerfile
+# Use Ubuntu with the appropriate architecture
+ARG ARCH=amd64
+FROM --platform=linux/${ARCH} ubuntu:latest
+
+# Set environment variables (timezone will be set at runtime)
+ENV DEBIAN_FRONTEND=noninteractive TERM="xterm-256color"
+
+# Install common dependencies and mise
+RUN apt-get update && apt-get install -y curl wget git jq vim nano unzip zip ssh ca-certificates \
+    gnupg lsb-release software-properties-common build-essential pkg-config tzdata sqlite3 && \
+    rm -rf /var/lib/apt/lists/*
+
+# Install AWS CLI and Amazon Q CLI with architecture detection
+ARG TARGETARCH
+RUN ARCH_AWS=$([ "$TARGETARCH" = "amd64" ] && echo "x86_64" || echo "aarch64") && \
+    curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-$ARCH_AWS.zip" -o awscliv2.zip && \
+    curl --proto '=https' --tlsv1.2 -sSf "https://desktop-release.codewhisperer.us-east-1.amazonaws.com/latest/q-$ARCH_AWS-linux.zip" -o q.zip && \
+    unzip awscliv2.zip && ./aws/install && rm -rf awscliv2.zip ./aws && \
+    unzip q.zip -d /tmp && chmod +x /tmp/q/install.sh && Q_INSTALL_GLOBAL=true /tmp/q/install.sh && \
+    rm -rf q.zip /tmp/q
+
+# Create non-root user and set up directories
+RUN useradd -ms /bin/bash dev && \
+    mkdir -p /home/dev/src /home/dev/.aws/amazonq/profiles /home/dev/.ssh && \
+    mkdir -p /home/dev/.local/share/amazon-q /home/dev/.cache/amazon-q && \
+    chown -R dev:dev /home/dev
+
+# Switch to non-root user
+USER dev
+WORKDIR /home/dev/src
+
+RUN echo 'export PS1="\[\033[01;32m\]q-dev\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ "' >> /home/dev/.bashrc
+
+# Initialize the SQLite database to ensure proper permissions
+RUN mkdir -p /home/dev/.local/share/amazon-q && \
+    touch /home/dev/.local/share/amazon-q/data.sqlite3 && \
+    chmod 644 /home/dev/.local/share/amazon-q/data.sqlite3
+
+# Install mise for managing multiple language runtimes
+RUN curl https://mise.run | sh && \
+    echo 'eval "$(~/.local/bin/mise activate --shims bash)"' >> ~/.bashrc && \
+    eval "$(~/.local/bin/mise activate --shims bash)" && \
+    ~/.local/bin/mise use -g python@latest uv@latest node@lts java@latest go@latest
+
+# Default command starts Amazon Q chat
+ENTRYPOINT [ "q" ]
+CMD ["chat"]
+```
+
+## Architecture Support
+
+The Dockerfile supports both x86_64 (amd64) and ARM64 architectures:
+
+```bash
+# For Intel/AMD processors
+docker build --build-arg ARCH=amd64 -t amazon-q-dev .
+
+# For ARM processors (M1/M2/M3 Macs, Graviton, etc.)
+docker build --build-arg ARCH=arm64 -t amazon-q-dev .
+```
+
+## Data Storage Architecture
+
+Amazon Q CLI stores its data in different locations:
+
+| Purpose | Container Path | Storage Method |
+|---------|---------------|----------------|
+| **Main Data Directory** | `/home/dev/.local/share/amazon-q` | Docker volume: `amazon-q-data` |
+| **Cache Directory** | `/home/dev/.cache/amazon-q` | Docker volume: `amazon-q-cache` |
+| **AWS Profile Data** | `/home/dev/.aws/amazonq` | Host mount from `~/.aws/amazonq` |
+| **Current Directory** | `/home/dev/src` | Host mount from current directory |
+
+## Customizing the Docker Run Command
+
+The default Docker run command used by the `q-dev` alias is:
+
+```bash
+docker run -it --rm \
+  -v "$(pwd):/home/dev/src" \
+  -v "${HOME}/.aws/credentials:/home/dev/.aws/credentials:ro" \
+  -v "${HOME}/.aws/config:/home/dev/.aws/config:ro" \
+  -v "${HOME}/.aws/amazonq:/home/dev/.aws/amazonq:rw" \
+  -v amazon-q-data:/home/dev/.local/share/amazon-q \
+  -v amazon-q-cache:/home/dev/.cache/amazon-q \
+  -v "${HOME}/.gitconfig:/home/dev/.gitconfig:ro" \
+  -v "${HOME}/.ssh:/home/dev/.ssh:ro" \
+  -e AWS_PROFILE \
+  -e AWS_REGION \
+  -e TZ \
+  amazon-q-dev
+```
+
+You can customize this by:
+
+1. **Adding resource limits**:
+   ```bash
+   docker run -it --rm \
+     --cpus=2 \
+     --memory=4g \
+     ... # other options
+   ```
+
+2. **Adding additional volumes**:
+   ```bash
+   docker run -it --rm \
+     -v "/path/to/host/dir:/path/in/container" \
+     ... # other options
+   ```
+
+3. **Adding environment variables**:
+   ```bash
+   docker run -it --rm \
+     -e ADDITIONAL_VAR=value \
+     ... # other options
+   ```
+
+## Customizing the Setup Script
+
+The `setup-q-dev-alias.sh` script can be modified to:
+
+1. **Change the Docker image name**:
+   ```bash
+   # Find this line
+   ALIAS_DEFINITION="alias q-dev='docker run -it --rm \
+     ... # options
+     amazon-q-dev'"
+   
+   # Change amazon-q-dev to your preferred image name
+   ```
+
+2. **Add additional volume mounts**:
+   ```bash
+   # Find the alias definition and add your volume mounts
+   ALIAS_DEFINITION="alias q-dev='docker run -it --rm \
+     ... # existing options
+     -v \"/path/on/host:/path/in/container\" \
+     amazon-q-dev'"
+   ```
+
+## Persistent Home Directory
+
+The Docker setup now includes a persistent home directory volume (`amazon-q-home`) that allows:
+
+1. **Package installations** to persist between sessions
+2. **Shell customizations** like aliases and environment variables
+3. **User configuration files** in the home directory
+4. **Global tool installations** that are available in all sessions
+
+### How It Works
+
+The persistent home directory is implemented as a Docker volume that's mounted at `/home/dev` in the container:
+
+```bash
+docker run -it --rm \
+  # Other mounts...
+  -v amazon-q-home:/home/dev \
+  # More options...
+  amazon-q-dev
+```
+
+This approach has some important considerations:
+
+1. **Mount Order**: The home directory volume is mounted first, then specific directories like `/home/dev/src` are mounted on top of it
+2. **Conflict Resolution**: If there's a conflict between the home volume and a specific mount, the specific mount takes precedence
+3. **Initial Setup**: On first use, the volume is initialized with the default home directory from the Docker image
+
+### Managing the Home Volume
+
+You can manage the persistent home volume with these commands:
+
+```bash
+# View the contents of the home volume
+docker run --rm -it -v amazon-q-home:/data ubuntu ls -la /data
+
+# Reset the home volume (removes all customizations)
+docker volume rm amazon-q-home
+docker volume create amazon-q-home
+
+# Backup the home volume
+docker run --rm -v amazon-q-home:/data -v $(pwd):/backup ubuntu tar czf /backup/amazon-q-home-backup.tar.gz -C /data .
+
+# Restore from backup
+docker run --rm -v amazon-q-home:/data -v $(pwd):/backup ubuntu bash -c "rm -rf /data/* && tar xzf /backup/amazon-q-home-backup.tar.gz -C /data"
+```
+
+### Container Networking
+
+By default, the container uses the default bridge network. To use a custom network:
+
+```bash
+# Create a custom network
+docker network create q-network
+
+# Run with custom network
+docker run -it --rm --network q-network ... amazon-q-dev
+```
+
+## Creating a Custom Image
+
+To create a custom image based on the default one:
+
+```dockerfile
+FROM amazon-q-dev
+
+# Add your customizations
+RUN apt-get update && apt-get install -y your-package
+USER dev
+RUN pip install your-python-package
+
+# Override entrypoint if needed
+ENTRYPOINT ["your-custom-entrypoint"]
+CMD ["your-default-command"]
+```
+
+Build with:
+```bash
+docker build -t custom-q-dev -f CustomDockerfile .
+```
diff --git a/docs/docker/running-in-docker.md b/docs/docker/running-in-docker.md
new file mode 100644
index 0000000000..1a8aa6d266
--- /dev/null
+++ b/docs/docker/running-in-docker.md
@@ -0,0 +1,300 @@
+# Running Amazon Q CLI in Docker
+
+This guide explains how to run Amazon Q CLI Chat in a Docker container for development and testing.
+
+## Quick Setup
+
+The easiest way to get started is to use our setup script:
+
+```bash
+# Download the setup script
+curl -O https://raw.githubusercontent.com/aws/amazon-q-developer-cli/main/docs/docker/setup-q-dev-alias.sh
+
+# Make it executable
+chmod +x setup-q-dev-alias.sh
+
+# Source it to add the alias to your current session
+source ./setup-q-dev-alias.sh
+```
+
+This will:
+1. Create necessary Docker volumes
+2. Build the Docker image (if it doesn't exist)
+3. Add a `q-dev` alias to your shell
+
+## Using Amazon Q in Docker
+
+After setting up, you can use Amazon Q CLI in Docker:
+
+```bash
+# Navigate to your project directory
+cd ~/my-project
+
+# Start Amazon Q chat
+q-dev
+
+# Or run a specific command
+q-dev --help
+```
+
+## Common Commands
+
+| Command | Description |
+|---------|-------------|
+| `q-dev` | Start Amazon Q chat in the current directory |
+| `q-dev --help` | Show Amazon Q CLI help |
+| `q-dev --entrypoint bash` | Start a bash shell instead of Q chat |
+
+## Development Workflow
+
+### Understanding Container Context
+
+When using Amazon Q in Docker, it's important to understand what context is available:
+
+- **Only the current directory** is mounted in the container
+- Amazon Q can only see and access files in your current directory (and subdirectories)
+- System-wide tools and dependencies inside the container may differ from your host machine
+- The container runs Ubuntu Linux, regardless of your host OS (macOS, Windows, etc.)
+
+### Best Practices for Development
+
+1. **Always navigate to your project root** before running `q-dev`
+   ```bash
+   cd ~/path/to/project-root
+   q-dev
+   ```
+
+2. **Add context from your project files**
+   ```
+   /context add README.md
+   /context add src/
+   ```
+
+3. **For larger codebases**, be selective about which files you add to context
+   ```
+   /context add src/main.py
+   /context add src/important_module/
+   ```
+
+4. **Use the container's bash shell** to explore or modify the environment
+   ```bash
+   q-dev --entrypoint bash
+   ```
+
+5. **Install additional dependencies** in the container if needed
+   ```bash
+   q-dev --entrypoint bash
+   pip install some-package
+   ```
+   Note: These changes will persist between container sessions thanks to the persistent home volume
+
+### Working with Different Languages
+
+The container comes with several language runtimes pre-installed:
+
+- **Python**: Use with `python` or `uv`
+- **Node.js**: Use with `node` or `npm`
+- **Java**: Available with `java` and `javac`
+- **Go**: Available with `go`
+- **AWS CLI**: Available with `aws`
+- **Git**: Available for version control
+
+Example workflows:
+
+**Python project:**
+```bash
+# Start a bash shell in the container
+q-dev --entrypoint bash
+
+# Create and run a Python script
+echo 'print("Hello from container")' > test.py
+python test.py
+```
+
+**Node.js project:**
+```bash
+# Initialize a Node.js project
+q-dev --entrypoint bash
+npm init -y
+npm install express
+echo 'console.log("Hello from Node.js");' > index.js
+node index.js
+```
+
+**AWS CLI usage:**
+```bash
+# AWS CLI commands use your host credentials
+q-dev --entrypoint bash
+aws s3 ls
+```
+
+## Common Development Tasks
+
+### Git Operations
+
+Git is pre-installed and configured to use your host's Git credentials:
+
+```bash
+# Inside the container
+git status
+git add .
+git commit -m "Update code"
+```
+
+### Running Tests
+
+Run tests for different languages:
+
+```bash
+# Python tests
+pytest tests/
+
+# JavaScript tests
+npm test
+
+# Go tests
+go test ./...
+```
+
+### Building Projects
+
+Build your projects inside the container:
+
+```bash
+# Node.js
+npm run build
+
+# Python
+python setup.py build
+
+# Go
+go build
+```
+
+### Using Amazon Q for Code Assistance
+
+Amazon Q is particularly helpful for coding tasks:
+
+```
+# Ask for code examples
+How do I implement a REST API in Express.js?
+
+# Get help with errors
+I'm getting this error: TypeError: Cannot read property 'map' of undefined
+
+# Request code reviews
+Can you review this function and suggest improvements?
+```
+
+## Adding Context
+
+Once inside the Q chat session, you can add context from your project:
+
+```
+# Add a single file
+/context add README.md
+
+# Add a directory and all its contents
+/context add src/
+
+# Add multiple specific files
+/context add package.json tsconfig.json
+
+# Clear all context
+/context clear
+```
+
+Remember that Amazon Q can only access files in the current directory that's mounted in the container. Files outside this directory are not accessible to Amazon Q.
+
+## Persistent Environment
+
+The Docker container is configured with three types of persistence:
+
+1. **Project Files**: Your current directory is mounted at `/home/dev/src` in the container
+2. **Amazon Q Data**: Stored in Docker volumes (`amazon-q-data` and `amazon-q-cache`)
+3. **Home Directory**: All user customizations are stored in the `amazon-q-home` volume
+
+This means:
+
+- **Installed packages** (via pip, npm, etc.) will persist between sessions
+- **Shell history** and customizations will be saved
+- **Configuration files** in your home directory will be preserved
+- **Global tools** you install will be available in future sessions
+
+For example, you can customize your environment once and have it available every time:
+
+```bash
+# First session
+q-dev --entrypoint bash
+pip install pandas matplotlib
+npm install -g typescript
+echo 'alias ll="ls -la"' >> ~/.bashrc
+exit
+
+# Later session - all customizations are still available
+q-dev --entrypoint bash
+python -c "import pandas; print(pandas.__version__)"
+tsc --version
+ll
+```
+
+## Limitations
+
+When using Amazon Q in Docker, be aware of these limitations:
+
+1. **File Access**: Only files in the current directory (and subdirectories) are accessible
+2. **System Context**: The container has its own Linux environment, separate from your host OS
+3. **Performance**: Running in Docker may be slightly slower than running natively
+4. **GUI Applications**: The container doesn't support GUI applications
+5. **Host Tools**: Tools installed on your host machine aren't available unless they're also installed in the container
+6. **Network Services**: Services running on your host (like local databases) need to be accessed via special Docker networking
+
+### Accessing Host Services
+
+If you need to access services running on your host machine (like a local database or web server):
+
+```bash
+# On macOS/Linux, use host.docker.internal to reference the host
+q-dev --entrypoint bash
+curl http://host.docker.internal:3000
+
+# For databases, use host.docker.internal instead of localhost
+mysql -h host.docker.internal -u user -p
+```
+
+## Troubleshooting
+
+If you encounter issues:
+
+1. **Rebuild the Docker image**:
+   ```bash
+   source ./setup-q-dev-alias.sh --rebuild
+   ```
+
+2. **Reset data volumes** if you have database errors:
+   ```bash
+   docker volume rm amazon-q-data amazon-q-cache
+   docker volume create amazon-q-data
+   docker volume create amazon-q-cache
+   ```
+
+3. **Reset home directory** if your environment becomes corrupted:
+   ```bash
+   docker volume rm amazon-q-home
+   docker volume create amazon-q-home
+   ```
+
+4. **Check Docker logs**:
+   ```bash
+   docker logs $(docker ps -q --filter ancestor=amazon-q-dev)
+   ```
+
+5. **Verify file access** by checking what's mounted:
+   ```bash
+   q-dev --entrypoint bash
+   ls -la /home/dev/src
+   ```
+
+## Advanced Configuration
+
+For advanced configuration options and customization details, see [customizing-docker-setup.md](customizing-docker-setup.md).
diff --git a/docs/docker/setup-q-dev-alias.sh b/docs/docker/setup-q-dev-alias.sh
new file mode 100755
index 0000000000..13f7d01b15
--- /dev/null
+++ b/docs/docker/setup-q-dev-alias.sh
@@ -0,0 +1,206 @@
+#!/usr/bin/env bash
+#
+# setup-q-dev-alias.sh
+#
+# This script creates shell aliases for running Amazon Q CLI in Docker,
+# with proper directory mapping for either macOS or Linux hosts.
+# It uses Docker volumes for persistent storage instead of direct host mapping.
+#
+# Usage:
+#   source ./setup-q-dev-alias.sh           # To add alias to current session
+#   ./setup-q-dev-alias.sh                  # To add alias to shell config only
+#   ./setup-q-dev-alias.sh --rebuild        # Force rebuild the Docker image
+#   source ./setup-q-dev-alias.sh --rebuild # Add alias and rebuild Docker image
+#
+# After running, you'll have the 'q-dev' alias available in your shell.
+
+# Detect if the script is being sourced or executed directly
+(return 0 2>/dev/null) && sourced=true || sourced=false
+
+# Check for rebuild flag
+force_rebuild=false
+for arg in "$@"; do
+  if [ "$arg" = "--rebuild" ]; then
+    force_rebuild=true
+  fi
+done
+
+# Detect operating system and architecture
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+# Map architecture to Docker platform
+if [ "$ARCH" = "arm64" ] || [ "$ARCH" = "aarch64" ]; then
+  DOCKER_ARCH="arm64"
+elif [ "$ARCH" = "x86_64" ]; then
+  DOCKER_ARCH="amd64"
+else
+  echo "⚠️  Unsupported architecture: $ARCH. Defaulting to amd64."
+  DOCKER_ARCH="amd64"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Print header
+echo "🚀 Setting up Amazon Q Developer Docker aliases"
+echo "==============================================="
+echo "🖥️  Detected architecture: $ARCH (using Docker platform: linux/$DOCKER_ARCH)"
+
+# Check if Docker is installed
+if ! command -v docker &>/dev/null; then
+  echo "❌ Error: Docker is not installed or not in PATH"
+  echo "Please install Docker first: https://docs.docker.com/get-docker/"
+  if [ "$sourced" = true ]; then
+    return 1
+  else
+    exit 1
+  fi
+fi
+
+# Create directories if they don't exist
+echo "📁 Creating required directories..."
+
+# AWS directory structure (common for both OS)
+mkdir -p "${HOME}/.aws/amazonq/profiles"
+
+# Create Docker volumes if they don't exist
+echo "📦 Setting up Docker volumes for Amazon Q data..."
+if ! docker volume inspect amazon-q-data &>/dev/null; then
+  docker volume create amazon-q-data
+  echo "Created volume: amazon-q-data"
+fi
+
+if ! docker volume inspect amazon-q-cache &>/dev/null; then
+  docker volume create amazon-q-cache
+  echo "Created volume: amazon-q-cache"
+fi
+
+# Create a persistent home directory volume if it doesn't exist
+if ! docker volume inspect amazon-q-home &>/dev/null; then
+  echo "📦 Creating persistent home directory volume..."
+  docker volume create amazon-q-home
+  echo "Created volume: amazon-q-home"
+fi
+
+# Define the alias with Docker volumes including persistent home directory
+ALIAS_DEFINITION="alias q-dev='docker run -itq --rm \\
+  -v \"\$(pwd):/home/dev/src\" \\
+  -v \"\${HOME}/.aws/credentials:/home/dev/.aws/credentials:ro\" \\
+  -v \"\${HOME}/.aws/config:/home/dev/.aws/config:ro\" \\
+  -v \"\${HOME}/.aws/amazonq:/home/dev/.aws/amazonq:rw\" \\
+  -v amazon-q-data:/home/dev/.local/share/amazon-q \\
+  -v amazon-q-cache:/home/dev/.cache/amazon-q \\
+  -v amazon-q-home:/home/dev \\
+  -v \"\${HOME}/.gitconfig:/home/dev/.gitconfig:ro\" \\
+  -v \"\${HOME}/.ssh:/home/dev/.ssh:ro\" \\
+  -e AWS_PROFILE \\
+  -e AWS_REGION \\
+  -e TZ \\
+  amazon-q-dev'"
+
+# Add the alias to the current shell session if sourced
+if [ "$sourced" = true ]; then
+  eval "$ALIAS_DEFINITION"
+  echo "✅ Alias 'q-dev' added to current shell session"
+fi
+
+# Detect shell and add alias to the appropriate config file
+SHELL_NAME="$(basename "$SHELL")"
+ALIAS_ADDED=false
+
+if [ "$SHELL_NAME" = "bash" ]; then
+  if [ -f "$HOME/.bashrc" ]; then
+    if ! grep -q "alias q-dev=" "$HOME/.bashrc"; then
+      echo -e "\n# Amazon Q Developer Docker alias\n$ALIAS_DEFINITION" >>"$HOME/.bashrc"
+      ALIAS_ADDED=true
+    fi
+  fi
+elif [ "$SHELL_NAME" = "zsh" ]; then
+  if [ -f "$HOME/.zshrc" ]; then
+    if ! grep -q "alias q-dev=" "$HOME/.zshrc"; then
+      echo -e "\n# Amazon Q Developer Docker alias\n$ALIAS_DEFINITION" >>"$HOME/.zshrc"
+      ALIAS_ADDED=true
+    fi
+  fi
+fi
+
+# Build or rebuild Docker image if needed
+build_image() {
+  if [ -f "$SCRIPT_DIR/Dockerfile" ]; then
+    echo "🔨 Building Docker image from $SCRIPT_DIR/Dockerfile for architecture: $DOCKER_ARCH..."
+    docker build --build-arg ARCH=$DOCKER_ARCH -t amazon-q-dev -f "$SCRIPT_DIR/Dockerfile" "$SCRIPT_DIR"
+    if [ $? -eq 0 ]; then
+      echo "✅ Docker image built successfully"
+    else
+      echo "❌ Failed to build Docker image"
+      return 1
+    fi
+  else
+    echo "❌ Dockerfile not found in $SCRIPT_DIR"
+    echo "Please create a Dockerfile first using the template from the documentation."
+    return 1
+  fi
+  return 0
+}
+
+# Check if Docker image exists or if rebuild is forced
+if [ "$force_rebuild" = true ]; then
+  echo "🔄 Forcing rebuild of Docker image..."
+  build_image
+elif ! docker image inspect amazon-q-dev &>/dev/null; then
+  echo "⚠️  The 'amazon-q-dev' Docker image doesn't exist yet."
+  echo "Would you like to build it now? (y/n)"
+  read -r BUILD_RESPONSE
+
+  if [[ "$BUILD_RESPONSE" =~ ^[Yy]$ ]]; then
+    build_image
+  else
+    echo "📝 You can build the image later with:"
+    echo "  docker build --build-arg ARCH=$DOCKER_ARCH -t amazon-q-dev -f $SCRIPT_DIR/Dockerfile $SCRIPT_DIR"
+    echo "  or run this script with the --rebuild flag"
+  fi
+fi
+
+# Print success message
+echo "✅ Setup complete!"
+if [ "$ALIAS_ADDED" = true ]; then
+  echo "The 'q-dev' alias has been added to your shell configuration."
+  if [ "$sourced" = false ]; then
+    echo "To use it in this terminal session, either:"
+    echo "  1. Run 'source ~/.${SHELL_NAME}rc'"
+    echo "  2. Start a new terminal session"
+  fi
+else
+  if [ "$sourced" = true ]; then
+    echo "The 'q-dev' alias is available for this terminal session."
+  else
+    echo "The alias was already in your shell configuration."
+    echo "To use it in this terminal session, run: source ~/.${SHELL_NAME}rc"
+  fi
+fi
+
+echo ""
+echo "📋 Usage:"
+echo "  q-dev                   # Start Amazon Q chat in the current directory"
+echo "  q-dev --help            # Show Amazon Q CLI help"
+echo "  q-dev --entrypoint bash # Start a bash shell instead of Q chat"
+echo ""
+echo "📦 Docker Volumes:"
+echo "  amazon-q-data          # Persistent storage for Amazon Q data"
+echo "  amazon-q-cache         # Persistent storage for Amazon Q cache"
+echo "  amazon-q-home          # Persistent home directory for user customizations"
+echo ""
+echo "🔧 Troubleshooting:"
+echo "  If you encounter database errors, you can reset the volumes with:"
+echo "  docker volume rm amazon-q-data amazon-q-cache && docker volume create amazon-q-data && docker volume create amazon-q-cache"
+echo ""
+echo "  If you want to reset your home directory customizations:"
+echo "  docker volume rm amazon-q-home && docker volume create amazon-q-home"
+echo ""
+echo "For more information, see the documentation in:"
+echo "  $SCRIPT_DIR/running-in-docker.md"
+
+# Exit with success if executed directly
+if [ "$sourced" = false ]; then
+  exit 0
+fi