diff --git a/deploy/.env.example b/deploy/.env.example
index 8ffc398..3d6e06f 100644
--- a/deploy/.env.example
+++ b/deploy/.env.example
@@ -1,60 +1,75 @@
-# ProcessGit deployment environment.
+# ProcessGit deployment configuration — single source of truth.
 #
-# Copy this file to ../.env (one level above deploy/) and fill in the values.
-# All variables marked `(required)` MUST be set; the others can be left blank
-# to accept defaults.
+# Copy this file to deploy/.env and edit. Docker Compose reads it
+# automatically for variable substitution AND the running containers
+# receive it via env_file. There is no second .env file at the project
+# root; everything operator-facing lives here.
 #
-# Generate the bearer token once:
-#   openssl rand -hex 32
-#
-# Then either:
-#   - Paste it into PROCESSGIT_UPDATER_TOKEN= below, or
-#   - Run: echo "PROCESSGIT_UPDATER_TOKEN=$(openssl rand -hex 32)" >> ../.env
+# After editing:
+#   docker compose -f deploy/docker-compose.yml up -d
 
-# -----------------------------------------------------------------------------
-# REQUIRED
-# -----------------------------------------------------------------------------
+# =============================================================================
+# Self-update sidecar (recommended; can be skipped — see below)
+# =============================================================================
 
-# Shared bearer token between the main ProcessGit app and the updater sidecar.
-# 64 hex chars = 32 bytes of entropy. Both containers read this from .env.
-# (required)
+# Shared bearer token between the main app and the updater sidecar.
+# 64 hex chars = 32 bytes of entropy.
+#
+# Required ONLY if you run the processgit-updater service. The main app
+# starts fine without it; you just won't have in-product self-updates.
+#
+# Generate with:
+#   openssl rand -hex 32
+#
+# Or append directly:
+#   echo "PROCESSGIT_UPDATER_TOKEN=$(openssl rand -hex 32)" >> deploy/.env
 PROCESSGIT_UPDATER_TOKEN=
 
-# -----------------------------------------------------------------------------
-# VERSION CONTROL
-# -----------------------------------------------------------------------------
-
-# Pin the ProcessGit image version. The updater rewrites this line when a
-# release is committed via the in-product UI, so the next `docker compose up`
-# reuses the same version after a host restart.
-# Defaults to `latest` if unset, which moves on every stable release —
-# acceptable for evaluation but not recommended for production.
+# Image version pin. The updater rewrites this line on a successful update
+# so the new version persists across host restarts. Leave at "latest" if
+# you're happy moving on every stable release, or pin to a specific
+# X.Y.Z for change-controlled deployments.
 PROCESSGIT_VERSION=latest
 
-# -----------------------------------------------------------------------------
-# UPDATER CONFIG (optional)
-# -----------------------------------------------------------------------------
-
-# GitHub repository the updater polls for releases.
+# GitHub repository the updater polls for new releases. Override if
+# you've forked.
 PROCESSGIT_UPDATER_REPO=Algomation-AI/ProcessGit
 
-# Slice 3A stub mode. The updater simulates the docker operations rather
-# than actually pulling/swapping containers. Default true while the docker
-# operations harden in Slice 3B.
-# Flip to `false` once Slice 3B (real docker calls) is merged AND you've
-# tested a stub-mode update flow end-to-end.
+# Stub mode. While true, the updater simulates docker operations rather
+# than actually pulling/swapping. Default true until you've validated
+# the architecture end-to-end against your deployment. Flip to "false"
+# to enable real updates.
 PROCESSGIT_UPDATER_STUB=true
 
-# -----------------------------------------------------------------------------
-# PROCESSGIT APP CONFIG (passed through env_file to the main container)
-# -----------------------------------------------------------------------------
-
-# Add any APP_* / GITEA_* / PROCESSGIT_* settings you want passed to the
-# main app container here. See:
+# =============================================================================
+# ProcessGit app config (passed through to the main container)
+# =============================================================================
+#
+# Any Gitea/ProcessGit configuration env vars can go here. The main
+# container receives this file via env_file, so every key=value pair
+# becomes an env var inside the container. See:
 #   https://docs.gitea.com/installation/install-with-docker
-# for the available config keys (ProcessGit inherits Gitea's config surface).
-
-# Example:
-# APP_NAME=ProcessGit
+#
+# Some common ones:
+#
 # DOMAIN=processgit.example.com
-# SSH_PORT=12222
+# SSH_DOMAIN=processgit.example.com
+# ROOT_URL=https://processgit.example.com/
+# APP_NAME=ProcessGit
+# DISABLE_REGISTRATION=true
+
+# =============================================================================
+# Opting out of the self-update sidecar
+# =============================================================================
+#
+# If you don't want the updater (e.g. you have change-control processes,
+# or you prefer to update manually): leave PROCESSGIT_UPDATER_TOKEN
+# blank above, and at `up` time list only the services you want:
+#
+#   docker compose -f deploy/docker-compose.yml up -d \
+#       processgit-init-perms processgit processgit-bootstrap
+#
+# The main app starts identically — you just won't have in-product
+# self-updates. You can always opt back in later by setting the token
+# and running:
+#   docker compose -f deploy/docker-compose.yml up -d processgit-updater
diff --git a/deploy/docker-compose.yml b/deploy/docker-compose.yml
index de3c9e1..1c67252 100644
--- a/deploy/docker-compose.yml
+++ b/deploy/docker-compose.yml
@@ -1,23 +1,29 @@
 # ProcessGit production-capable deployment.
 #
-# Two ways to run this:
+# Quick start (any operator, any host):
 #
-#   1. Build locally from source (dev / first install):
-#        docker compose -f deploy/docker-compose.yml up --build -d
+#   cp deploy/.env.example deploy/.env
+#   # If you want the self-update sidecar (recommended):
+#   echo "PROCESSGIT_UPDATER_TOKEN=$(openssl rand -hex 32)" >> deploy/.env
+#   docker compose -f deploy/docker-compose.yml up -d
 #
-#   2. Pull from GHCR (production / after first install):
-#        docker compose -f deploy/docker-compose.yml pull
-#        docker compose -f deploy/docker-compose.yml up -d
+# All operator configuration lives in `deploy/.env` (a single file next to
+# this compose file). Compose reads it automatically for variable
+# interpolation, and the app/bootstrap services pass its contents through
+# via env_file. There is no second .env file at the project root anymore.
 #
-# The `processgit-updater` service drives in-product updates from the
-# admin UI. It requires:
+# Opting out of the self-update sidecar
+# -------------------------------------
+# The `processgit-updater` service is included by default but is fully
+# optional. To run without it:
 #
-#   - $PROCESSGIT_UPDATER_TOKEN in .env (generate once via:
-#       openssl rand -hex 32  >> /tmp/x && sed -i "s/^/PROCESSGIT_UPDATER_TOKEN=/" /tmp/x
-#     then append /tmp/x to your .env). See deploy/.env.example.
-#   - /var/run/docker.sock bind-mounted (it needs to drive `docker pull` etc).
-#   - deploy/ directory bind-mounted, so the updater can find this file and
-#     persist the new PROCESSGIT_VERSION to .env on commit.
+#   docker compose -f deploy/docker-compose.yml up -d \
+#       processgit-init-perms processgit processgit-bootstrap
+#
+# The main app starts identically; you simply lose the in-product update
+# story. If PROCESSGIT_UPDATER_TOKEN isn't set in .env, the main app
+# starts anyway (the variable is optional for it). Only the updater
+# service requires a token.
 
 services:
   processgit:
@@ -37,15 +43,17 @@ services:
     volumes:
       - processgit-data:/data
     env_file:
-      - ../.env
+      - .env
     environment:
       USER_UID: "1000"
       USER_GID: "1000"
       APP_NAME: "ProcessGit: Git for Processes"
       PROCESSGIT_SEED_STRICT: "false"
-      # So the main app knows how to reach the updater
+      # So the main app knows how to reach the updater. Empty value is OK
+      # if the updater service isn't running — the main app just won't
+      # surface self-update controls in the admin UI.
       PROCESSGIT_UPDATER_URL: "http://processgit-updater:9000"
-      PROCESSGIT_UPDATER_TOKEN: ${PROCESSGIT_UPDATER_TOKEN:?PROCESSGIT_UPDATER_TOKEN is required - see deploy/.env.example}
+      PROCESSGIT_UPDATER_TOKEN: ${PROCESSGIT_UPDATER_TOKEN:-}
     healthcheck:
       test: ["CMD-SHELL", "wget -qO- http://localhost:3000/api/v1/version >/dev/null 2>&1 || exit 1"]
       interval: 5s
@@ -70,7 +78,7 @@ services:
     volumes:
       - processgit-data:/data
     env_file:
-      - ../.env
+      - .env
     environment:
       PROCESSGIT_API_BASE: "http://processgit:3000/api/v1"
     entrypoint: ["/bin/sh", "-c"]
@@ -86,7 +94,7 @@ services:
     restart: unless-stopped
     image: ghcr.io/algomation-ai/processgit-updater:${PROCESSGIT_VERSION:-latest}
     environment:
-      PROCESSGIT_UPDATER_TOKEN: ${PROCESSGIT_UPDATER_TOKEN:?PROCESSGIT_UPDATER_TOKEN is required - see deploy/.env.example}
+      PROCESSGIT_UPDATER_TOKEN: ${PROCESSGIT_UPDATER_TOKEN:?The processgit-updater service requires PROCESSGIT_UPDATER_TOKEN in deploy/.env. Generate one with `openssl rand -hex 32` and add it. Or omit this service from `docker compose up` if you don't want self-updates.}
       PROCESSGIT_UPDATER_REPO: ${PROCESSGIT_UPDATER_REPO:-Algomation-AI/ProcessGit}
       PROCESSGIT_UPDATER_APP_CONTAINER: processgit
       PROCESSGIT_UPDATER_COMPOSE_FILE: /deploy/docker-compose.yml
@@ -101,8 +109,6 @@ services:
       #   - read docker-compose.yml to drive `docker compose up --no-deps`
       #   - persist the new PROCESSGIT_VERSION to .env on commit
       - .:/deploy
-      # Parent dir (project root) RO for .env access via ../.env path
-      - ..:/host-root:ro
 
 volumes:
   processgit-data: