Merge remote-tracking branch 'origin/main' into bcherry/cli-first-docs

Author: bcherry

.dockerignore

@@ -1,3 +1,9 @@
+# Project tests
+test/
+tests/
+eval/
+evals/
+
 # Python bytecode and artifacts
 __pycache__/
 *.py[cod]
@@ -39,10 +45,29 @@ coverage/
 
 # Project docs and misc
 README.md
+CONTRIBUTING.md
 LICENSE
 
-# Project tests
-test/
-tests/
-eval/
-evals/
+# Coding agent files
+.claude/
+.codex/
+.cursor/
+.windsurf/
+.gemini/
+.cline/
+.clinerules
+.clinerules/
+.aider*
+.cursorrules
+.cursorignore
+.cursorindexingignore
+.clineignore
+.codeiumignore
+.geminiignore
+.windsurfrules
+CLAUDE.md
+AGENTS.md
+GEMINI.md
+.github/copilot-instructions.md
+.github/personal-instructions.md
+.github/instructions/

.gitignore

@@ -10,4 +10,24 @@ KMS
 *.egg-info
 .pytest_cache
 .ruff_cache
-.claude/settings.local.json
+
+# Claude Code
+.claude/settings.local.json
+.claude/worktrees/
+
+# OpenAI Codex
+.codex/config.local.toml
+
+# Gemini CLI
+.gemini/history/
+.gemini/tmp/
+.gemini/google_accounts.json
+.gemini/installation_id
+.gemini/oauth_creds.json
+
+# Cursor
+.cursor/chat/
+.cursor/rules/*.local.mdc
+
+# GitHub CLI
+.github/personal-instructions.md

Dockerfile

@@ -10,19 +10,13 @@ FROM ghcr.io/astral-sh/uv:python${PYTHON_VERSION}-bookworm-slim AS base
 # the application crashes without emitting any logs due to buffering.
 ENV PYTHONUNBUFFERED=1
 
-# Create a non-privileged user that the app will run under.
-# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user
-ARG UID=10001
-RUN adduser \
-    --disabled-password \
-    --gecos "" \
-    --home "/app" \
-    --shell "/sbin/nologin" \
-    --uid "${UID}" \
-    appuser
+# --- Build stage ---
+# Install dependencies, build native extensions, and prepare the application
+FROM base AS build
 
 # Install build dependencies required for Python packages with native extensions
 # gcc: C compiler needed for building Python packages with C extensions
+# g++: C++ compiler needed for building Python packages with C++ extensions
 # python3-dev: Python development headers needed for compilation
 # We clean up the apt cache after installation to keep the image size down
 RUN apt-get update && apt-get install -y \
@@ -50,20 +44,35 @@ RUN uv sync --locked
 # (Excludes files specified in .dockerignore)
 COPY . .
 
-# Change ownership of all app files to the non-privileged user
-# This ensures the application can read/write files as needed
-RUN chown -R appuser:appuser /app
+# Pre-download any ML models or files the agent needs
+# This ensures the container is ready to run immediately without downloading
+# dependencies at runtime, which improves startup time and reliability
+RUN uv run "src/agent.py" download-files
+
+# --- Production stage ---
+# Build tools (gcc, g++, python3-dev) are not included in the final image
+FROM base
+
+# Create a non-privileged user that the app will run under.
+# See https://docs.docker.com/build/building/best-practices/#user
+ARG UID=10001
+RUN adduser \
+    --disabled-password \
+    --gecos "" \
+    --home "/app" \
+    --shell "/sbin/nologin" \
+    --uid "${UID}" \
+    appuser
+
+# Copy the application and virtual environment with correct ownership in a single layer
+# This avoids expensive recursive chown and excludes build tools from the final image
+COPY --from=build --chown=appuser:appuser /app /app
 
 # Switch to the non-privileged user for all subsequent operations
 # This improves security by not running as root
 USER appuser
 
-# Pre-download any ML models or files the agent needs
-# This ensures the container is ready to run immediately without downloading
-# dependencies at runtime, which improves startup time and reliability
-RUN uv run src/agent.py download-files
-
-# Run the application using UV
+# Run the AgentServer using UV
 # UV will activate the virtual environment and run the agent.
-# The "start" command tells the worker to connect to LiveKit and begin waiting for jobs.
+# The "start" command tells the AgentServer to connect to LiveKit and begin waiting for jobs.
 CMD ["uv", "run", "src/agent.py", "start"]

README.md

@@ -56,6 +56,18 @@ The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants
 
 ## Dev Setup
 
+Create a project from this template with the LiveKit CLI (recommended):
+
+```bash
+lk cloud auth
+lk agent init my-agent --template agent-starter-python
+```
+
+The CLI clones the template and configures your environment. Then follow the rest of this guide from [Run the agent](#run-the-agent).
+
+<details>
+<summary>Alternative: Manual setup without the CLI</summary>
+
 Clone the repository and install dependencies to a virtual environment:
 
 ```console
@@ -76,6 +88,8 @@ lk cloud auth
 lk app env -w -d .env.local
 ```
 
+</details>
+
 ## Run the agent
 
 Before your first run, you must download certain models such as [Silero VAD](https://docs.livekit.io/agents/build/turns/vad/) and the [LiveKit turn detector](https://docs.livekit.io/agents/build/turns/turn-detector/):